Troubleshooting and FAQ

Short answers for operators. The full procedures live in Production and Staging Deploy and Recovery. Installation problems such as Docker permissions and port 8000 are in Installation — Common Problems.

How do I deploy a tagged release to staging or production?

Check out the Git tag, then rebuild:

git fetch --tags
git checkout <release-tag>
just prod-rebuild

just prod-rebuild rebuilds the API and workers, runs just prod-ui-up to recreate the operators Console with a key from API_KEY_CLIENTS, then runs smoke checks. Pin tags; do not deploy from a moving main. Version-to-version jumps use Upgrading InfoConnect.

Why does the Console load but Search, Status, or Chat fail?

Rendering HTML, reaching the backend, and reaching it with an accepted key are three different checks. The console's real signal is GET /api/ready (also the container healthcheck): 200 only when INFOCONNECT_API_KEY is configured, the backend reports itself semantically healthy, and a protected endpoint accepts the key — otherwise 503 with a stable code (server_key_missing, server_key_rejected, backend_unreachable, backend_degraded, capabilities_unexpected). /api/health proves only that a key was injected; backend /health is unauthenticated.

just prod-up, just prod-ui-up, and just prod-rebuild resolve the key via just prod-console-key and refuse before any Compose mutation when it is missing, blank, or not in API_KEY_CLIENTS. just prod-ui-check gates deploy success on readiness plus one authenticated read.

To recover an existing deployment, run:

just prod-ui-up
curl -fsS http://127.0.0.1:3000/api/ready

Use <configured-api-key> as the placeholder in examples — never commit a live key. Details: Console readiness: /api/ready, not the homepage.

I changed .env and ran docker compose restart. Nothing changed. Why?

Compose interpolates .env into environment: when the container is created. .env is not mounted into the API, workers, or Console. docker compose restart restarts the old process with the old environment.

Recreate instead:

just prod-up         # API and workers
just prod-ui-up      # Console, including API_KEY_CLIENTS → INFOCONNECT_API_KEY

Image or Dockerfile changes need just prod-rebuild, which includes prod-ui-up. Details: Why docker compose restart does not pick up .env.

just prod-up printed Celery worker revision conflict detected before startup. Should I wipe?

No. The checker does not print a Python class name. Match stderr for Celery worker revision conflict detected before startup., Expected deployment revision:, and Offending worker node(s):. Stop the stale workers and keep the index:

just prod-down       # data preserved — look for "Production stopped (data preserved)."
just stop            # only if a local/dev worker is still on the same broker
just prod-rebuild

Do not run just prod-down clean or just wipe to clear a revision conflict. Those delete Qdrant and Redis volumes. Details: Celery worker revision conflict recovery.

I turned on Chat Web mode, but web search is rejected. Is the UI broken?

Usually not. Answer Mode (Auto / Docs-only / Web) is a per-turn Console choice. WEB_SEARCH_ENABLED is the server deployment gate (default false). When the gate is off, Auto runs as Docs-only and an explicit Web turn is rejected; the mode control collapses to Docs-only.

curl -fsS http://localhost:8000/web-search/capabilities \
  -H "X-API-Key: <configured-api-key>"

Run that curl on the deployment host or through the approved SSH tunnel. HTTP 401 means the key is missing from API_KEY_CLIENTS. Unreachable means just status / just prod-logs api on that host. If "enabled" does not match .env, recreate the API with just prod-up rather than docker compose restart. If "enabled": true but the Console has no Web Answer Mode, run just prod-ui-up, hard-refresh, and check /api/ready — that is the Console UI gate, not the .env gate. Enabling WEB_SEARCH_ENABLED does not switch Chat into Web mode. Details: Web search enablement vs Chat Answer Mode.

What should I check after a production deploy?

Follow the post-deploy acceptance checks on the deployment host or through the approved SSH tunnel: Product Version (just prod-verify-version), healthy /health, authenticated search with <configured-api-key>, Console /api/ready plus the authenticated read (not only the homepage), web-search capabilities matching WEB_SEARCH_ENABLED, and workers on the current Git revision. Redis and Qdrant need not be publicly exposed; laptop-side localhost curls are not a failed deploy.

Where else should I look?

Symptom	Guide
First-time Docker / Just install	Installation
Environment variables	Configuration
Recipe list	Justfile Commands
Qdrant / Redis backup	Backup, Restore, and Rollback
Go-live evidence	Go-Live Checklist