Troubleshooting
Audience: Anyone running or deploying the Case Automation MCP Server who encounters an error.
What you will accomplish: Diagnose and resolve the most common setup, runtime, and deployment issues.
Estimated time: Varies by issue — most fixes take under 5 minutes.
Setup and installation
| Symptom | Cause | Fix |
|---|---|---|
requires-python >=3.12 error | System Python is 3.11 or earlier | Always run commands through uv run … — uv resolves the correct Python version |
uv: command not found | uv not installed | Install: curl -LsSf https://astral.sh/uv/install.sh | sh |
uv sync fails with resolver error | Lock file out of date | Delete .venv/ and uv.lock, then uv sync --extra dev |
AttributeError: 'PrintLogger' in tests | Outdated conftest.py | Pull latest main; the _reset_global_singletons fixture handles this |
Environment and configuration
| Symptom | Cause | Fix |
|---|---|---|
RuntimeError: Intake services not configured | configure_services() not called | Use the official entry point cam.sidecar.main which bootstraps all services |
KeyError: workflow 'intake' not registered | register_intake_workflow() not called | Same — use the official entry point |
| Database connection refused | PostgreSQL not running or wrong URL | Verify CAM_DATABASE_URL in .env; run docker ps to check containers |
| Redis connection refused | Redis not running | Verify CAM_REDIS_URL; run docker compose up -d redis |
| Encryption key error on startup | Invalid KEK format | KEK must be base64-encoded 32 bytes; use python -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())" to generate |
Database migrations
| Symptom | Cause | Fix |
|---|---|---|
Can't locate revision | Migration directory out of sync | Run uv run alembic current to check state; if stuck, uv run alembic stamp head to realign |
alembic upgrade head fails with SQL error | Schema conflict from partial migration | Inspect the failed migration; apply manually or reset: docker compose down -v && docker compose up -d postgres then re-run |
Tests
| Symptom | Cause | Fix |
|---|---|---|
Tests fail on PrintLogger | Outdated conftest | Pull latest main branch |
424 passed becomes fewer | New test regression | Run uv run pytest -q --tb=short for failure details; check recent changes |
Flaky test on test_reminder_fires_exactly_once | Race in scheduler mock | This test is intentionally skipped in CI — not a blocker |
Workflow runtime
| Symptom | Cause | Fix |
|---|---|---|
Workflow stuck in awaiting_approval | No approver has acted on the gate | Call workflow.approve via MCP tool, or visit /approvals/{token} in the sidecar |
Workflow in parked status | Fatal error or auth failure | Check audit log for the step that failed; fix the underlying issue, then re-drive from the sidecar |
ConnectorError(auth) | OAuth token expired or invalid | Re-authorise the connector; check CAM_SECRET_BACKEND configuration |
ConnectorError(rate_limit) | Too many requests to vendor API | Automatic retry with backoff; if persistent, reduce polling frequency |
| Duplicate email sent | Idempotency key not provided | Always provide idem_key on email.send and write tools |
| Privileged document routed externally | Should never happen — this is a safety invariant | If observed, this is a critical bug — report immediately. The privilege gate should block this regardless of approval |
Sidecar and webhooks
| Symptom | Cause | Fix |
|---|---|---|
| Webhook returns 401 | Invalid HMAC signature | Verify the webhook secret configuration matches the provider's dashboard |
Webhook returns duplicate | Event already processed | Normal behaviour — idempotent ingestion; check audit log for the original processing |
| Approval page shows "token expired" | Gate TTL exceeded (default 24h) | Re-trigger the workflow run; the expired token cannot be revived |
| Sidecar health endpoint returns 500 | Application startup failure | Check sidecar logs: uv run uvicorn cam.sidecar.main:app --port 8001 with --log-level debug |
Deployment
| Symptom | Cause | Fix |
|---|---|---|
| Build fails with "Module not found" | Missing npm dependencies | Run pnpm install or npm install before building |
| MDX pages not rendering | Nextra config issue | Verify next.config.mjs has output: 'export' and nextra wrapper |
| Styles not loading | CSS import missing | Check _app.tsx imports ../styles/globals.css |
| 404 on page refresh | SPA routing without redirects | Ensure trailingSlash: true in next.config.mjs and redirects in netlify.toml |
| Search not working | Missing search index | Nextra generates index at build time; check for build warnings |
Still stuck?
If your issue isn't listed here, check the GitHub issues (opens in a new tab) or open a new one with the full error output and your environment details (python --version, uv --version, OS).
Last updated: 2026-06-01