Skip to main content

​
Troubleshooting

Start with the smallest truth source: health, status, config, then worker preflight. Do not jump to live dispatch while basic checks are failing. If topology or terminology is unclear, start with the current runtime snapshot before debugging a specific symptom.

​
API will not start

Check that ENOCH_CONFIG points to readable JSON, required callback/token fields are set, control_api_bearer_token is set, and configured paths are valid for the service user. 
python3 -m json.tool "$ENOCH_CONFIG"
uv run python -m compileall -q enoch_control_plane tests

​
Dashboard returns unauthorized

Use the configured control_api_bearer_token as a bearer token. Do not confuse it with completion_callback_token or worker_wake_gate_bearer_token. The HTML shell is served at /dashboard; dashboard data routes require token-bearing requests.

​
Dispatch is blocked

Read status first: 
curl -fsS -H "Authorization: Bearer $ENOCH_CONTROL_TOKEN" \
  "$ENOCH_BASE_URL/control/api/status" | python3 -m json.tool
Common blockers include queue pause, maintenance mode, no queued candidate, active lane already running, worker preflight failure, invalid dispatch script path, or live dispatch not intentionally enabled.

​
Worker preflight fails

Check the worker URL, token, firewall, and worker service logs. Then run the preflight endpoint with strict:false to separate reachability from stricter readiness requirements.

​
Worker gate never completes

Possible causes include active child processes, strict CPU/GPU thresholds, unavailable or noisy GPU telemetry, wrong workload profile, or stale-process reaper markers that are too narrow. Inspect processes and telemetry before lowering thresholds.

​
Paper drafting fails

Check that paper/evidence records exist, evidence sync paths are reachable when enabled, paper_writer_provider is valid, provider API keys are available for synthetic.new, and fallback behavior is understood.

​
Corpus quality fails

The corpus policy rejects placeholder citations, fake citations, peer-review claims, implied human authorship, and missing provenance/evidence unless explicitly stated. Fix the artifact or keep it out of release.