DOCS · FOR TEAMS
Troubleshooting
Symptom, cause, fix — for the failures that actually happen.
Start with specd doctor. It reports config, server, database, embeddings, credential, identity and default project in dependency order, and skips what an earlier failure makes unknowable — so one broken thing reads as one broken thing.
Getting it running
| Symptom | Cause | Fix |
|---|---|---|
DATABASE_URL is required — copy .env.example to .env | No .env at the repo root yet | cp .env.example .env, then retry. |
Same error, .env exists | Not at the repo root, or the value is empty | grep DATABASE_URL .env from the repo root should print a real value — the loader looks there, not at the shell's cwd. |
| API cannot reach Postgres | pnpm infra:up never ran, or Docker is down | docker ps should list specd-postgres as healthy. |
EADDRINUSE on :3000 / :4000 | A previous pnpm dev is still running | lsof -nP -iTCP:3000 -sTCP:LISTEN, stop it, retry. |
| Schema-shaped error right after pulling | New migrations landed | pnpm db:migrate — idempotent. |
| Web app renders but has no data in it | The API died at startup, and node --watch keeps a crashed process alive — so pnpm dev still looks healthy | curl localhost:4000/api/health; nothing answering confirms it. The reason is in the API's own output, scrolled past by the web server's. The next row is the usual cause. |
@specd/db does not provide an export named … | packages/*/dist is missing or older than its src | pnpm --filter "./packages/*" build. dist is gitignored and no install hook builds it, so this is also needed after any pull that touched a package. |
Web dev server 500s after pnpm build | next build and next dev share apps/web/.next in incompatible shapes | Stop the dev server, rm -rf apps/web/.next, start it again. |
Tests and CI
| Symptom | Cause | Fix |
|---|---|---|
| A whole test file reports skipped | No database reachable — or the suite's own beforeAll threw | Bring Postgres up. If it persists, suspect the suite's setup rather than the database. |
| CI fails complaining that tests skipped | The Postgres-dependent suites self-skipped in CI | That is the point — a broken CI database would otherwise look identical to a pass. Fix the service, not the check. |
pnpm typecheck fails on a clean checkout | The workspace packages have not been built | pnpm --filter "./packages/*" build first; pnpm typecheck does this itself. |
Agents and integrations
| Symptom | Cause | Fix |
|---|---|---|
| Spec generation fails with an error about credentials | No model credential for this project | Set ANTHROPIC_API_KEY, or SPECD_AI_MODE=subscription_runner with Claude Code signed in. See Bring your own model. |
| Merges are not detected | No webhook reaching the API | Locally, forward deliveries (gh webhook forward or a tunnel) — or use the "I merged it" button. See GitHub. |
| Every webhook delivery fails the signature check | GITHUB_WEBHOOK_SECRET does not match the sender | gh webhook forward re-signs with its own secret and prints it — use that value while forwarding. |
| The API refuses to start, naming an embedding dimension | The configured embedding model does not produce 1024-dimension vectors | Use one that does (mxbai-embed-large fits; nomic-embed-text is 768). |
| A dispatched job never starts | No paired runner, or the daemon is not running | Check Settings → runners for last-heard-from. specd runner pair reports connectivity at pairing time for exactly this reason. |
| A job keeps being reclaimed and finally fails | The runner dies mid-job | After three reclaims specd fails it as repeatedly abandoned rather than bouncing forever. Look at the runner, not the queue. |
| A build reports could not run rather than failed | The toolchain is missing on the machine that built it | Nothing was proved either way. Fix the environment and re-run — this is deliberately not reported as a test failure. |
Resetting
pnpm infra:down is a plain docker compose down — the data volume survives. For a true reset:
docker compose down -v
pnpm infra:up && pnpm db:migrate && pnpm db:seed