> ## Documentation Index
> Fetch the complete documentation index at: https://solo-09d10f60.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose common Enoch setup, dispatch, worker, evidence, and paper-writer problems.

# 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](/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.

```bash theme={null}
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 canonical HTML shell is served at `/control/dashboard-v2`; dashboard data routes require token-bearing requests or a scoped backend dashboard session.

## Dispatch is blocked

Read status first:

```bash theme={null}
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.