Troubleshooting

Diagnose bootstrap, GitHub, queue, sandbox, provider, configuration, and publication failures.

Start from the durable workflow or task record, then correlate its identifiers with server and worker logs.

Server does not start

DATABASE_URL, TASUKU_PUBLIC_URL, and TASUKU_BOOTSTRAP_TOKEN are required — set every required runtime value.
TASUKU_MASTER_KEY must be a base64-encoded 32-byte key — generate it with openssl rand -base64 32 and preserve it.
TASUKU_MASTER_KEY_VERSION must be a positive integer — use an integer of at least 1.
TASUKU_ENV must be development, test, or production — correct the environment value.

INVALID_GITHUB_APP_CONFIGURATION — repeat the manifest conversion with the expected fields and matching public URL.
GITHUB_APP_IDENTITY_UNAVAILABLE — the App identity has not been configured or cannot be resolved.
GITHUB_EMAIL_PERMISSION_REQUIRED — add Email addresses: read to the App and reauthorize it.
New signup is rejected — check TASUKU_AUTO_SIGNUP_DOMAINS for an exact verified-email domain; parent domains do not include subdomains.

Confirm that the repository is still selected in the GitHub installation, synchronized into Tasuku, explicitly enabled, and eligible under the event, draft, author, path, and changed-file policy. Then check GitHub webhook delivery and Tasuku's delivery deduplication record.

Configuration will not save

Docker requires a non-empty image.
Daytona requires api_url, an api_key or secret reference, and image.
Lambda requires function_name and region.
MCP URLs must use HTTPS and transports must be HTTP or SSE.
Review strictness must be LOW, MEDIUM, or HIGH.
Changed-file limit must be 1–5000; comment limit must be 1–100.

Task repeatedly fails

Inspect attempt history to identify the stage:

repository token or clone;
secondary repository preparation;
sandbox creation;
Codex or Claude authentication and model selection;
MCP or tool access;
output parsing or artifact validation;
GitHub publication.

Transient failures retry with backoff. A repeating deterministic error needs configuration, runtime, or repository correction; restarting workers alone will reproduce it.

Queue appears stuck

Check Postgres health, worker database connectivity, worker logs, job lease timestamps, heartbeats, and available capacity. An expired lease can be reclaimed after a worker crash, but an active heartbeat prevents another worker from taking the same job.

Database migration history was reset

Fresh development databases start from the consolidated 00001 baseline. A database that completed the earlier multi-file history through version 56 can continue with compatibility migration 00057 and later. Older or partially migrated databases are not supported; recreate those databases or their Docker volumes instead of editing the Goose migration ledger.

Restored secrets no longer work

Verify that the restored TASUKU_MASTER_KEY exactly matches the key used for the database. A new key with the same version number is still a different key.