Troubleshooting

Work from the earliest failing stage: boot, health, capture, analysis, upload, then dashboard. A running process or a green health endpoint does not verify the entire pipeline.

The booter exits immediately

Run it from healthcam-agent, with the Python environment that has python-dotenv installed. Confirm Docker is running. Read the first exception in the terminal rather than only the final shutdown message.

Leave the legacy blink-counter service disabled. If a port is in use, stop the conflicting application or adjust the service manifest. The booter does not detect ports occupied by unrelated processes.

Services run but recording does not start

Booting starts services, not capture. After checking readiness, explicitly call POST http://127.0.0.1:8008/start or use the web recording control. Check /status for the pipeline phase.

If the browser cannot reach the agent, test with a terminal first. The web app contacts the user's machine, not the Vercel server. Confirm the local agent URL, browser local-network permissions, and the orchestrator's allowed origins. A hosted HTTPS page can also be restricted from contacting local HTTP services by browser policy.

The camera is unavailable

Close video calls and other camera users. Confirm OS camera permissions and that ffmpeg is installed on PATH. The current Windows/macOS device picker uses the system FFmpeg command even when recording can use the bundled binary.

Use a camera-supported resolution and frame rate in config.json. Windows capture currently requests a raw yuyv422 input for lossless FFV1 recording, which some camera modes do not support. Linux currently selects /dev/video0; check that it is the intended camera.

Inspect the camera health response and the native service output in the booter terminal. The segment directory should gain video files and matching JSON sidecars while recording.

Application context is missing

On Linux, install xdotool and x11-utils and use an X11 session. Native Wayland tracking is not implemented. On macOS, verify Accessibility/Automation permissions for the process launching the tracker. Then inspect GET http://127.0.0.1:8002/context while a normal desktop application is focused.

The analyzer fails or returns no result

Read the analyzer's container log. For BPM, a Mac or CPU-only machine cannot run the current CUDA implementation; disable BPM and use the blink path, or move to a compatible NVIDIA setup. On NVIDIA machines, check the drivers and container runtime as well as the analyzer health endpoint.

For blink, verify the MediaPipe model exists and the container dependencies support your architecture. Its manifest still includes legacy GPU metadata; the actual blink implementation uses MediaPipe/OpenCV and does not request NVIDIA in its Compose file.

Poor face/eye visibility can produce an explicit no-result reason. Improve framing and lighting, then repeat a short test. Do not treat a no-result response as a valid zero measurement.

Upload fails or files accumulate

docker logs --tail 100 orchestrator

After editing .env, stop and restart the booter so containers are recreated with the updated environment. A successful upload is required before normal cleanup. The queue is in memory, so interrupted work is not durably retried across restarts.

Stop the camera to let the pipeline drain. If errors prevent progress, stop the whole pipeline, then shut down the booter. Inspect retained files and remove only the test data you no longer need. Do not manually remove files while services are processing them.

Recordings exist but the dashboard is empty

A blink-only run does not generate BPM metrics. The Recordings table is currently BPM-oriented and can show zero for blink-only payloads.

For BPM, confirm the personal account owns the dashboard, the analyzer produced valid numeric data, and aggregation has run. The SQL keeps successful results with numeric BPM from 40 to 200 and positive segment duration. Local development needs a manual aggregation command; production scheduling can lag.

Per-app charts show only apps with more than 30 minutes of tracked time. A short test is expected to leave them empty. Use the upload response and Recordings for immediate evidence.

Starting again after a code change

The booter installs only missing service environments or container images. It does not automatically rebuild an existing image after you change source or dependencies.

Stop capture and the booter. To rebuild one service, provide the same ID and port recorded in the runtime registry. For example, from healthcam-agent, in macOS/Linux shells:

HEALTHCAM_SERVICE_ID=blink-dt-0-0-1 HEALTHCAM_SERVICE_PORT=8039 docker compose -f services/blink-dt-0-0-1/compose.yml build

In Windows PowerShell:

$env:HEALTHCAM_SERVICE_ID = "blink-dt-0-0-1"
$env:HEALTHCAM_SERVICE_PORT = "8039"
docker compose -f services/blink-dt-0-0-1/compose.yml build

Restart the booter after the build. Avoid running the legacy root Compose stack alongside the manifest-driven services.

Report a useful issue

Include the operating system, Python/Docker versions, camera model, enabled services, the first failing stage, and a short redacted error excerpt. State whether the failure happens before recording or only during analysis/upload.

Do not attach API keys, environment files, private window titles, or raw webcam video. Use the GitHub issue tracker or the project's support form for a concise report.