> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acusight.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

# 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://<APP_HOST>` 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:

```bash theme={null}
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 `APP_HOST` and `LAN_IP` are correct in `.env`. LAN deployments: re-run `scripts/install-acusight.sh` to re-detect; cloud deployments: edit `.env` directly.

## 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:

```bash theme={null}
# 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**: `LAN_IP` not set or incorrectly auto-detected

**Solution**:

1. Check `.env` file has correct IP. LAN deployments: re-run `scripts/install-acusight.sh` to re-detect; cloud deployments: edit `.env` directly.
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**:

* Pre-load the image manually (see [Device Provisioning Guide](/guides/deploy/device-provisioning))
* Or configure a local registry mirror

## 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 data service is running: `docker compose ps data`

### Batch stuck in "collecting" status

**Cause**: Batch timeout not triggered or auto-close disabled

**Solution**:

1. Manually close the batch via API:
   ```bash theme={null}
   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:

| Port | Service     | Required For                             |
| ---- | ----------- | ---------------------------------------- |
| 8080 | Core API    | Device provisioning, heartbeats, uploads |
| 443  | Caddy HTTPS | Browser access                           |
| 9000 | Portainer   | Container 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

```bash theme={null}
# 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 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](https://github.com/ArcturusNetworks/acusight/issues)
3. **Open an issue**: Include logs, steps to reproduce, and environment details