Runbooks

Troubleshooting recipes for the HiveCFM stack, grouped by where the problem bites first. Open this section when something is broken right now — the goal is to get you back to working, not to teach the underlying system.

Each runbook follows the same shape: Symptom → Likely cause → Fix → Verify → Prevent. Written for the problems we actually hit on this repo, with the exact env vars, ports, and scripts HiveCFM uses. Scan the symptom list first. If nothing matches, check Run it locally and the DevOps section.

Local setup

• Port conflicts — “address already in use” on 3001, 3002, 5433, 6380, 4100, 9000, or 9001. Find the offender and free the port.
• Build OOM — next build dies with “JavaScript heap out of memory”. Raise the Node heap ceiling or build just @hivecfm/web.

Backend

• Postgres refused — ECONNREFUSED 127.0.0.1:5433 at dev time. Usually the Postgres container is not running or the dev-ports override is missing.
• Migration stuck — pnpm db:migrate:dev hangs, reports drift, or refuses to reapply. Inspect Prisma status and resolve the stuck row.

Auth

• Hub 401 — Calls from core to the Go Hub return 401 Unauthorized. Keys on the two sides drifted or the header is missing.
• NextAuth callback mismatch — Login redirects to the wrong origin or fails the CSRF check. NEXTAUTH_URL disagrees with what the browser sees.

Infrastructure

• Docker volumes — Postgres refuses to initialise, MinIO rejects old credentials, Superset looks half-migrated. Dirty volumes from a prior run.