Reference

Troubleshooting

Start from the visible symptom and check the narrowest dependency boundary first.

The API deploy exits immediately

Configuration validation failed. Read the first error in the API log. Common causes are a missing Redis URL, an encryption key that does not decode to 32 bytes, a Clerk issuer with a trailing slash, a dashboard origin with a path, or an incomplete S3 configuration.

Run /preflight --check-storage in the same provider environment. Do not paste the environment values into a terminal transcript or issue.

Migration fails but the API database URL works

Check MIGRATION_DATABASE_URL. Supabase transaction pooling on port 6543 is not appropriate for the migration advisory lock. Use the session pooler on port 5432 or a reachable direct connection.

/health returns 503

The API process is reachable but PostgreSQL is not. Check network reachability, percent-encoding in the password, TLS requirements, project pause state, and connection limits.

Dashboard shows a network or WebSocket error

Compare the exact browser origin with CLERK_ALLOWED_DASHBOARD_ORIGINS. The value must include https://, must not include a path, and must not end in /. Then confirm VITE_API_BASE_URL was present during the dashboard build. Changing it after the build requires a rebuild.

A direct dashboard URL returns 404

The static host is missing the single-page application fallback. Vercel must apply vercel.json. Cloudflare Pages must publish the checked-in public/_redirects file into dist. Other static hosts must return index.html with status 200 for routes that are not real files.

Invitation acceptance says verified_email_required

The active Clerk session lacks the custom email and boolean email_verified claims, or the primary email is not verified. Update the normal session token customization, then sign out and back in to refresh the token.

Attachments fail but text works

Run /preflight --check-storage. Confirm the bucket exists, remains private, the endpoint has no trailing slash, and the access keys are S3 server credentials. For Supabase use the direct storage hostname and path addressing.

Relay connects but cannot send

Open Apple Messages and send manually first. Then check the installed Relay app’s Automation permission for Messages. Terminal access or a development binary does not prove the installed signed app has permission.

Relay cannot read history

Check Full Disk Access for the installed app identity and location. Restart Relay after changing the permission. Do not infer success from Terminal having Full Disk Access.

Search is empty after Redis restarts

Redis holds a derived encrypted search projection. Complete or re-run a contact snapshot so the API rebuilds it. Check for a no-eviction policy if entries disappear under memory pressure.

Further issues

If the steps above do not resolve the problem, email sidd@feeble.io. Include the setup step that failed, the hosting provider, and the exact error message. Do not include passwords, API keys, connection strings, encryption keys, or customer message content.