Docs · Operate
Troubleshooting
Every error below actually happened during development. If this guide is wrong, that is a bug — please open an issue.
| Symptom | Cause | Fix |
|---|---|---|
error during connect: … docker engine is not running | Docker Desktop isn't started. | Start Docker Desktop, wait for it to be green, retry docker compose up -d. |
port is already allocated / bind: address already in use on 5433 | Another container or a second copy of this compose project owns 5433. | docker compose down in any other checkout; or change the host port in docker-compose.yml and DATABASE_URL consistently. |
DATABASE_URL is required (from db:migrate) | packages/db/.env is missing or empty. | cp packages/db/.env.example packages/db/.env, then migrate again. |
password authentication failed for user "postgres" | You're talking to a different Postgres (e.g. a local 5432 install). | Confirm the URL uses port 5433 and points at localhost, and the compose stack is up. |
relation "user" does not exist | Migrations were never applied to this volume. | Run pnpm --filter @hirelens/db db:migrate and re-run tests. |
Orchestrator integration tests fail, everything else passes | Database container stopped or unreachable. | docker compose up -d, wait for healthy in docker compose ps, retry. |
type "vector" does not exist | Non-Docker Postgres without pgvector. | Use the pinned pgvector/pgvector:pg16 image, or run db:extensions with a superuser URL. |
EADDRINUSE on 3000 / 4000 / 6006 | A stale dev server holds the port. | Kill it (npx kill-port 3000) or close the old terminal; ports are fixed by convention. |
401 sign_in_failed right after a fresh API sign-up | better-auth requires an Origin header matching a trusted origin on sign-up. | Sign up once via the web UI, or send -H "Origin: http://localhost:3000" with curl/CLI. |
503 llm_not_configured from derive/score in Docker | Empty-string HIRELENS_LLM_* values count as "set" through compose interpolation. | Put real provider/model/key values in the root .env, then docker compose up -d api. |
LlmRuntimeError: … Proto field is not repeating, cannot start list (Gemini) | Gemini rejects JSON schemas with arrays nested in arrays — our rubric schemas use that shape. | Already fixed: generateStructured auto-falls back to validated JSON-text mode per provider. Update to current main. |
hirelens score hangs after creating a job | jobs create without --jd reads the JD from stdin, which never closes in scripts. | Always pass --jd <file> (or pipe input). |
Every pnpm command fails with a corepack stack trace (ERR_PNPM_IGNORED_BUILDS) | A placeholder value in pnpm-workspace.yaml allowBuilds. | Set every allowBuilds entry to true or false, then pnpm install. |
CRLF formatting diffs flood a PR on Windows | git core.autocrlf rewrites line endings. | Run pnpm format before committing; the repo expects LF (.gitattributes + Biome). |
Still stuck?
Open an issue with your OS, Node/pnpm/Docker versions, the exact command, and the full error — the contact page has the links. Security issues go through the private process in SECURITY.md, never a public issue.