Troubleshooting¶

The app can't reach the backend¶

The status bar shows no server latency, or Test Connection says Unreachable.

Is the backend running? In the folder that contains docker-compose.yml, run:
```
docker compose ps
```
All services should show running. If not, start them with docker compose up -d.
Is the gateway answering? Open http://localhost:8080/api/v1/health in a browser. If it doesn't load, look at the gateway's logs:
```
docker compose logs api-gateway
```
Is the URL right? Under Customize → Backend, the Server URL must end in /api/v1. Leave it blank to use http://localhost:8080/api/v1.
Backend on another machine? It must be started with QCLM_BIND=0.0.0.0, and the firewall must allow port 8080. See Using a shared lab server.

The backend is slow to start, or services keep restarting¶

Give Docker more memory. The full stack needs about 4–6 GB. In Docker Desktop, go to Settings → Resources → Memory.
Wait for Kafka. On the first start, Kafka can take up to a minute to become healthy, and the services wait for it.

Check the logs of the restarting service:

docker compose logs --tail=100 processing-service

`docker compose up` fails with "port is already allocated"¶

Another program is using port 8080. Choose another port in a .env file:

QCLM_PORT=8090

Then set the app's Server URL to http://localhost:8090/api/v1.

`docker compose pull` says "denied" or "unauthorized"¶

The images are on the GitHub Container Registry. If they are not yet public, you need access to the project, plus a login:

docker login ghcr.io

macOS says QCLM "is damaged" or "can't be opened"¶

The app is not notarized yet. Right-click QCLM in Applications and choose Open, or use System Settings → Privacy & Security → Open Anyway. See Installation.

If macOS still says the app is "damaged", remove the quarantine flag:

xattr -dr com.apple.quarantine /Applications/QCLM.app

Live frames don't appear during a scan¶

Frames are pushed over a live event stream from the gateway (/events). If the stream drops, the app falls back to polling the backend, so frames still arrive, just less smoothly. If nothing arrives at all:

docker compose logs acquisition-service processing-service api-gateway

Importing a file fails¶

Check that the format is supported.
For ENVI, select the .hdr file. The data file must sit next to it.
For Zarr, only uncompressed or zlib-compressed float (f4 / f8) arrays are supported.
The processing service log shows the exact parser error:
```
docker compose logs processing-service
```

Reporting a problem¶

Click the gear button → About and include the version shown there, your OS, and the relevant docker compose logs output.