Troubleshooting¶

A directory of the most common problems and their fixes.

Install / setup¶

`Set JWT_SECRET in docker/.env`¶

The Docker compose file refuses to start without the three required secrets.

JWT_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
INTERNAL_SECRET=$(openssl rand -hex 32)

cat >> docker/.env <<EOF
JWT_SECRET=$JWT_SECRET
ENCRYPTION_KEY=$ENCRYPTION_KEY
INTERNAL_SECRET=$INTERNAL_SECRET
EOF

Or just re-run ./docker/setup.sh — it generates them automatically.

`pnpm install` fails on Windows¶

Make sure you have:

Node.js 22 (not 18 / 20) — node -v.
Visual Studio Build Tools or windows-build-tools for native modules.
Long path support enabled (git config --system core.longpaths true).

`pnpm db:migrate` errors with "extension pgvector not found"¶

Your PostgreSQL doesn't have pgvector. On Ubuntu:

sudo apt install -y postgresql-16-pgvector

Or use the bundled Docker Postgres which has it preinstalled:

docker compose -f docker/docker-compose.yml up postgres -d

Runtime¶

`502 Bad Gateway` from nginx¶

The API container is still booting (10–30 seconds on first start). Check:

docker compose -f docker/docker-compose.yml logs api | tail -50

If you see a Postgres connection error, the migrate container hasn't finished. Wait, then refresh.

Browser shows the nginx default page¶

docker/setup.sh couldn't replace the default site. Manually:

sudo rm -f /etc/nginx/sites-enabled/default
sudo systemctl reload nginx

Browser shows a self-signed certificate warning¶

Expected when:

You used ./docker/setup.sh without a domain.
You used HOST=192.168.x.x ./docker/setup.sh.
You're running on localhost.

Either accept the warning, or import /etc/ssl/doable/cert.pem into your OS/browser trust store. For a real cert, deploy with DOMAIN=....

`ECONNREFUSED ::1:4000` from the web app¶

Node's resolver picked IPv6 first. Make sure your .env uses 127.0.0.1, not localhost:

NEXT_PUBLIC_API_URL=http://127.0.0.1:4000

Live preview is blank¶

Open the preview iframe URL directly in a new tab. Possible causes:

The project's Vite dev server crashed — check services/api logs for [dev-server] lines.
A build error blocks the page — open the editor's preview pane to see the error overlay.
The visual edit bridge couldn't be injected (rare; see Visual Edit).

Restart the dev server: editor toolbar → Run.

Real-time collaboration not syncing¶

Check that services/ws is running (docker compose ps ws, or tmux attach -t doable window 2).
Check NEXT_PUBLIC_WS_URL matches the actual WS URL — ws:// for HTTP, wss:// for HTTPS.
The reverse proxy must forward the Upgrade: websocket header. nginx config snippet:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

"No AI provider configured" in chat¶

Confirm at least one of ANTHROPIC_API_KEY, OPENAI_API_KEY, COPILOT_CLI_PATH, COPILOT_CLI_URL is set in the API process's environment.
Restart after editing .env: docker compose restart api or systemctl restart doable.
If using Copilot CLI, run it once interactively to verify auth: copilot auth status.

Chat hangs without streaming¶

Check the browser network panel — the /chat/.../messages request should be text/event-stream. If it's application/json, the request never reached SSE — usually a proxy buffering issue.
nginx: add proxy_buffering off; for /chat and /plan locations.

Out of disk¶

PROJECTS_ROOT grows over time as more projects are created. Clean up:

# Find the largest projects
du -sh /path/to/projects/* | sort -h | tail
# Delete soft-deleted projects with no recent activity
psql -c "SELECT id FROM projects WHERE deleted_at < now() - interval '90 days'"
# (Then rm the matching directories.)

For Docker, the api_projects volume — docker volume inspect doable_api_projects.

Out of memory during build¶

Symptoms: pnpm build killed, JavaScript heap out of memory.

Add swap (the bare-metal installer adds 2 GB by default).
Increase Node's heap: NODE_OPTIONS=--max-old-space-size=4096 pnpm build.

AI¶

Permission prompt for every tool call¶

Your workspace policy is too strict (set to "ask" for many tools). Tighten or relax it from Workspace Settings → AI → Tools.

`credit_exhausted` for everyone¶

The workspace's AI credit balance is at 0. Either:

Top up via Stripe (if billing is enabled), or
Disable Stripe to remove the limit, or
Adjust the limit from Workspace Settings → AI → Limits (admin).

Anthropic / OpenAI 429 rate limit¶

Doable retries automatically, then surfaces the error. Solutions:

Bump your provider plan.
Configure a fallback provider order in workspace settings.
Reduce parallel chats.

Database¶

`too many connections` on PostgreSQL¶

DATABASE_POOL_SIZE × number_of_processes exceeds Postgres' max_connections. Lower DATABASE_POOL_SIZE (default 20) or raise Postgres' limit.

Slow queries¶

psql -c "SELECT pid, now() - query_start AS dur, query
         FROM pg_stat_activity
         WHERE state = 'active' ORDER BY dur DESC LIMIT 20;"

The frequent culprit is the analytics rollup queries — check the schedule in services/api/src/analytics/.

Deployment¶

`cloudflared` connection failures¶

journalctl -u cloudflared -e

Common: cert expired (cloudflared tunnel login to renew); tunnel deleted in Cloudflare console.

Caddy not auto-issuing SSL¶

Check journalctl -u caddy -f while loading the site for the first time. Common causes: DNS doesn't resolve to the host, port 80 isn't reachable from Let's Encrypt, ACME rate limit hit.

For Cloudflare Tunnel deployments, Caddy can still get a cert because it issues via DNS-01 if you add the Cloudflare DNS plugin — or you let Cloudflare provide the public-facing cert and Caddy serves on HTTP internally.

Still stuck?¶

Check the GitHub Issues.
Search the GitHub Discussions.
File a new issue with: deployment mode, OS, the exact error, the relevant log snippet, and the steps you took.