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 run both recipes:

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

just prod-rebuild rebuilds and smokes the API and workers. just prod-ui-up recreates the operators Console with a key from API_KEY_CLIENTS. 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?

The Console container can start healthy with an empty INFOCONNECT_API_KEY. just prod-up / just prod-rebuild starts console from Compose using ${INFOCONNECT_API_KEY:-}, and the project-root .env.example does not set that variable. The healthcheck only loads the HTML shell.

Same-origin /api/* routes fail closed until a key is injected. Run:

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

Use <configured-api-key> as the placeholder in examples — never commit a live key. Details: Why the Console can start with an empty INFOCONNECT_API_KEY.

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 still need just prod-rebuild, then just 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
just prod-ui-up

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/health — 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/health (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