Troubleshooting
The errors you will actually see, what they mean, and the fix.
Connection problems
connection refused / timeouts
- Check the host and port: direct is
5432, pooled is6432. A URL pasted into the wrong slot is the usual suspect. - The project must be in
readystate — a project mid-provision or mid-restore does not accept connections yet.capydb status --remoteor the dashboard shows the state. - Corporate networks sometimes block outbound 5432/6432; test from another network before blaming the database.
TLS errors (SSL connection required, server does not support SSL)
- Keep
sslmode=requirein the URL. CapyDB requires TLS; clients that strip query params (some env-var templating, some GUI clients) produce exactly this error. - For asyncpg,
sslmodeis not a recognized parameter — passssl=truein connect args instead.
too many connections / remaining connection slots are reserved
The plan's connection budget (15 / 30 / 60 for Vibe / Ship / Business) is shared by everything you run.
- Move app traffic to the pooled URL — that is what it is for.
- Shrink client-side pool sizes (
max,pool_size,RAILS_MAX_THREADSmath). - Check Observability for idle direct sessions holding slots — GUI clients left open are a classic.
prepared statement "..." already exists
You are running a prepared-statement-caching driver through the transaction pooler. Fixes per stack are in the framework guides: prepare: false (postgres.js), prepared_statements: false (Rails), simple protocol mode (pgx), statement_cache_size=0 (asyncpg) — or use the direct URL.
API and job errors
project must be ready / project is not ready for this operation
The operation needs a ready project, and yours is provisioning, restoring, importing, or failed. Wait for the in-flight job (capydb jobs get --job-id ... --wait) or check what failed in the dashboard. Jobs run one lifecycle mutation at a time per project by design.
Import preflight failures
| Check | Fix |
|---|---|
source_size_within_plan fail | The source is bigger than the plan's storage limit. Trim the source (drop logs/archives tables), or upgrade the plan. The warn threshold is 80% — heed it; databases grow. |
source_version_compatible fail | The source runs a newer Postgres major than the target (17). Downgrades are not supported. Realistically: import from a logical copy on ≤17, or wait for CapyDB to offer the newer major. |
extensions_available_on_target fail | The detail names the offending extensions. Drop unused ones on the source (DROP EXTENSION ...), replace replaceable ones (uuid-ossp → pgcrypto), or contact support about the allowlist. |
could not inspect source database | The source is not reachable from the internet, credentials are wrong, or TLS failed. The same check will fail the real import, so fix it now. See the provider playbooks for reachability gotchas (RDS security groups, Fly private networking, Render allow-lists). |
The worker re-runs these checks before the destructive part of an import — passing preflight yesterday does not exempt a source that grew overnight.
preview database must be ready to extend its ttl / preview gone
Previews expire on their TTL — that is the feature. If a preview vanished, it expired or was deleted; create a new one (the GitHub Action and branch integrations do this idempotently). Extend TTLs before they lapse: capydb preview extend <id> --ttl-hours 48.
ttl_hours must be between 1 and 168
The hard preview TTL ceiling is 7 days. For something permanent, that is a project, not a preview.
Webhooks
Signature verification keeps failing
- Verify against the raw request body, byte-for-byte. Parsing then re-serializing JSON is the number-one cause of mismatches (Express: use
express.raw()on the webhook route). - The signed string is
"<t>.<body>"— timestamp, a literal dot, then the body. HMAC-SHA256, hex output, compared againstv1=. - Confirm you are using the current secret: rotating the endpoint secret invalidates the old one immediately.
- See the reference implementation.
Deliveries marked failed
Eight attempts exhausted (backoff 30s → 30m). Common causes: receiver returning non-2xx (redirects count as failures), timeouts from doing work inline — return 204 first, process after. The delivery history on the endpoint shows the status code and error per attempt.
CLI
no api key available; pass --api-key, set CAPYDB_API_KEY, or run 'capydb login'
Exactly what it says — the CLI fails fast instead of hanging on missing auth. Run capydb login, or provide a key for non-interactive use.
login session expired or not found; run 'capydb login' again / login session poll was rejected (unauthorized)
The browser device-login flow timed out or was completed in a different context. Re-run capydb login; use --no-open to print the URL if the browser hand-off is the problem (SSH sessions, containers).
capydb link cannot find the project
--project accepts an id, slug, or name; names must match a project in the active organization — check capydb whoami and switch the dashboard org if you logged in against the wrong one.
Still stuck
Include the project id, the job id (for lifecycle failures), and the exact error string when contacting support — the audit log and job records make those three things instantly diagnosable.