Troubleshooting

Start with the symptom you can observe. The Service page usually identifies whether the problem is configuration, build, runtime, scheduling, access, or storage and keeps the evidence needed for the next step.

Last updated

My deploy is blocked

Read the blocker on the Service page before starting another deploy.

  • A required environment variable has no value. Supply it on the Environment tab.
  • Two sources want to set the same variable. Choose the Project secret, built in database connection, or other source shown in the conflict.
  • A logical database or other resource choice needs confirmation.

Clearing the named item continues the prepared deployment. See Secrets and environment variables.

My site is down

Use the Service status and current diagnosis.

  • Stopped in gray means the Service is paused. Resume it.
  • Degraded means the process is running but health checks are failing. Read the boot and live logs.
  • A red incident means the process crashed. Open the preserved crash output or use Copy for AI.
  • A maintenance response can follow a required migration failure. Deploy a fix or use the explicit recovery action. See Database migrations.
  • A failed update does not normally mean the current site is down. The previous healthy version keeps serving when the new version fails before cutover.

My deploy failed

The tracker identifies the failed phase and attaches a diagnosis.

  • Review failures point to code Tokay could not interpret or a setup decision that could not be resolved.
  • Build failures usually point to dependencies, compilation, or private package access.
  • Go Live failures mean the built version did not start or pass its checks. Inspect the new version's logs, apply the fix, and use Try Again.

A proposed fix appears as a diff and is never applied automatically.

I pushed and no update appeared

Check the Project's auto-deploy setting. When auto-deploy is off, the push can be ready while the Service waits for Update.

For GitHub, confirm that the push went to the connected branch. In a repository with several Services, Tokay deploys only the Services whose relevant source changed.

git push was rejected

An SSH permission error usually means the expected key was not offered. An HTTPS authentication error usually means the git token is wrong, revoked, or missing repository access. A read only role or token can clone but cannot push.

A conflict means another push changed the remote history. Pull before pushing again. Rate limiting means more than 60 pipeline triggering pushes arrived in a minute or 10 pipelines were already active, which often indicates an automated loop.

See SSH keys and git tokens.

My scheduled job did not run

Open the Logs tab first. A listed run with an error means the schedule fired and the command failed.

When no run appears, check the schedule, timezone, and the next run countdown on the Service page. A paused scheduled job does not fire. Killed / Timed out means the run was stopped before it completed.

The Service ran out of memory

The process needed more memory than the Workspace machine had available. Check the Usage views for the Service and its neighbors. Process data in smaller batches or streams when possible. See Your server.

My webhook is not receiving requests

Use Send Test Event. A successful test means the deployed Service works and the sender configuration needs attention.

Listening for first request... means no request has reached the URL. Requests listed with errors mean the sender connected and the handler failed. Inspect the recorded payload, fix the code, and replay it with Copy as cURL.

A coworker cannot open the app

Check the Project audience and the access log. The denial row explains whether the email, domain, or Workspace membership matched the rule. Also check spam when the magic link email does not arrive.

See Who can open your app.

Files written by the app disappeared

Files outside persistent storage reset with a deploy or restart.

If the current Service instance still has the file, rescue it into Saved storage before another deployment. Then mark the directory persistent or write future data to /tokay/data. See Service files and Files and persistent storage.

A file already removed by an instance replacement cannot be recovered from that temporary filesystem.

A source snapshot expired

The stored source view for a very old deployment can expire. The commit hash still identifies the version, and git managed repositories keep their history in git.

For a problem not covered here, email hello@tokay.io with the Service name and the approximate time of the event.