Skip to main content

​
Troubleshooting

This guide covers common issues you might encounter when using Acusight.

​
Authentication Issues

​
Browser shows “Your connection is not private”

Cause: Self-signed TLS certificate (expected for local development) Solution:
  • Chrome: Click “Advanced” → “Proceed to <IP> (unsafe)”
  • Firefox: Click “Advanced” → “Accept the Risk and Continue”
This only needs to be done once per browser.

​
crypto.subtle error on login page

Cause: Browser accessed over plain HTTP (not localhost) Solution: Use https://<SERVER_EXTERNAL_IP> instead of http://. The OIDC PKCE flow requires a secure context, which is only available over HTTPS or http://localhost.

​
OIDC redirect fails or returns invalid_request

Cause: Zitadel OIDC app missing HTTPS redirect URIs Solution: Wipe the platform-init state and re-initialize: 
docker compose stop zitadel platform-init core frontend caddy
docker run --rm -v acusight_platform_config:/cfg alpine rm -f /cfg/.init-complete /cfg/platform.env
docker run --rm -v acusight_zitadel_init:/init alpine rm -rf /init/*
docker compose exec postgres psql -U user -d postgres -c "DROP DATABASE IF EXISTS zitadel;"
docker compose exec postgres psql -U user -d postgres -c "CREATE DATABASE zitadel OWNER zitadel_user;"
docker compose up -d

​
Login page shows “Failed to fetch” or network error

Cause: Core service not running or unreachable Solution:
  1. Check core service is running: docker compose ps core
  2. Check core logs: docker compose logs core
  3. Verify SERVER_EXTERNAL_IP is correct in .env

​
Device Provisioning Issues

​
409 DEVICE_EXISTS when provisioning

Cause: A device with the same Docker daemon ID is already registered Solution: Delete the existing device and re-provision: 
# Find the device ID
curl http://<SERVER>:8080/api/core/devices \
  -H "Authorization: Bearer <TOKEN>" | jq '.data[] | {id, device_id, name}'

# Delete it
curl -X DELETE http://<SERVER>:8080/api/core/devices/<DEVICE_ID> \
  -H "Authorization: Bearer <TOKEN>"

# Re-run provisioning

​
401 INVALID_TOKEN when provisioning

Cause: Provisioning token is invalid, expired, or already used (single-use) Solution: Create a new provisioning token in the dashboard or via API.

​
Agent logs show “connection refused”

Cause: SERVER_EXTERNAL_IP not set or incorrect Solution:
  1. Check .env file has correct IP
  2. Rebuild core: docker compose up --build -d core
  3. Verify connectivity: curl http://<IP>:8080/metrics

​
Setup script fails with “Failed to pull image”

Cause: Edge device cannot reach Docker Hub or image registry Solution:

​
Container Management Issues

​
Portainer shows “Agent not available”

Cause: Portainer Edge Agent not connected Solution:
  1. Check if edge agent is running on device: docker ps | grep portainer-agent
  2. Verify edge key was received during provisioning
  3. Check device firewall allows outbound connections to Portainer

​
Portainer agent hangs inside container

Cause: Normal behavior - waits for portainer_env file that doesn’t exist in cloud mode Solution: This is harmless and can be ignored. The core platform doesn’t use the agent for functionality.

​
Data Pipeline Issues

​
Images not appearing in batches

Cause: Data service not receiving notifications Solution:
  1. Check core service logs: docker compose logs core | grep upload
  2. Check data service logs: docker compose logs data
  3. Verify Redis is running: docker compose ps redis

​
Batch stuck in “collecting” status

Cause: Batch timeout not triggered or auto-close disabled Solution:
  1. Manually close the batch via API: 
    curl -X PATCH http://<SERVER>:8080/api/data/batches/<BATCH_ID> \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"stage": "complete"}'
  2. Check batch configuration settings

​
MinIO shows “Access Denied”

Cause: Incorrect credentials or bucket permissions Solution:
  1. Verify MinIO credentials in .env
  2. Check bucket exists: docker compose exec minio mc ls local/
  3. Ensure bucket policy allows access

​
Networking Issues

​
Cannot access services from edge devices

Cause: Firewall blocking ports Solution: Ensure these ports are open on the host machine:
PortServiceRequired For
8080Core APIDevice provisioning, heartbeats, uploads
443Caddy HTTPSBrowser access
9000PortainerContainer management (optional)

​
Browser cannot connect to https://<IP>

Cause: Caddy not running or port 443 blocked Solution:
  1. Check Caddy status: docker compose ps caddy
  2. Check Caddy logs: docker compose logs caddy
  3. Verify port 443 is not used by another service

​
Performance Issues

​
Slow image uploads

Cause: Network latency or image size Solution:
  • Use LAN mode if devices can reach MinIO directly
  • Compress images before upload
  • Check network bandwidth

​
High memory usage

Cause: Large number of batches or images in memory Solution:
  1. Increase container memory limits in docker-compose.yml
  2. Configure pagination for large queries
  3. Archive old batches

​
Debugging Commands

# Check all service status
docker compose ps

# View logs for all services
docker compose logs -f

# View logs for specific service
docker compose logs -f core

# Restart a service
docker compose restart core

# Rebuild and restart a service
docker compose up --build -d core

# Check database connectivity
docker compose exec postgres psql -U user -d acusight -c "SELECT 1"

# Check Redis connectivity
docker compose exec redis redis-cli ping

# Check MinIO connectivity
docker compose exec minio mc ls local/

​
Getting Help

If you can’t resolve your issue:
  1. Check logs: Most issues leave traces in service logs
  2. Search issues: GitHub Issues
  3. Open an issue: Include logs, steps to reproduce, and environment details