Troubleshooting

Use this page when deployment fails or your app does not behave as expected. Tell your AI agent what happened and share the error message to ask it to investigate.

Find your symptom

Symptom	What to check
Cannot deploy	Identify the failing stage
Cannot open the app	Permissions, available slots, response time limits
Changes do not appear	Page updates, applying secrets
Data is not retained	Storage location
Scheduled or background work does not run	Scheduled jobs, background processing

Ask your AI agent to investigate

An AI agent with the Keelson Agent Skill can use the CLI to retrieve app status, deployment logs, app logs, and access logs. It uses the permissions of the account signed in to the CLI, so that account needs permission to view the app’s logs. You can give the agent the app name, time, and symptom without finding and pasting the logs yourself.

In this app, [action] causes [symptom]. It happened at [date and time]. Check the status and logs, then explain the cause and how to resolve it.

Include any error code (code), message (message), and suggested action (hint). If the issue cannot be resolved by changing the app, such as a service outage, gather the information under Contact support.

Identify the failing stage

On the app page in the console, Overview summarizes the failure, Details on a deployment under Deploys shows its failure details, and Logs shows app logs. Start with the overview, then ask your agent to investigate the details.

CLI commands and log details

A deploy_id identifies a deployment. Find it in CLI output or the console’s Deploys tab.

keelson status                   # App and latest deployment status
keelson diagnose <deploy_id>     # Diagnose a failed deployment
keelson logs deploy <deploy_id>  # Progress and stored failure details
keelson logs app <slug>          # App standard output and standard error

Even if the app exited during startup, keelson logs deploy and keelson diagnose can show saved startup logs. These may identify the failing code or missing configuration.

Which logs are saved

Failed deployments retain build and startup details. Use them to investigate dependency, Dockerfile, secret, configuration, and migration errors afterward. Check saved startup logs for tracebacks and process errors.

Build output for successful deployments is not retained. If neither progress logs nor saved failure details are available, the CLI explains why logs are unavailable.

Stage	Where to look	Common causes
Before upload: CLI preflight checks	Command output	Missing `go.mod` for Go; only pnpm / yarn lockfiles for Node; `pip install` in `command`; missing `db.mode`; unquoted `env` values
Validation	`code` and `message`	Leftover `workers` / `databases`, reserved names, plan limits
Build	Deployment logs	Dependency resolution failure, mismatched `package.json` and `package-lock.json`, private registries, Go packages requiring cgo, build script errors
Startup	Saved app startup logs from `keelson logs deploy <deploy_id>`	Not listening on `0.0.0.0`, hardcoded `PORT`, exceptions caused by missing secrets
Health checks	Saved startup logs, then app logs	App exits during startup, `/` returns 5xx, startup exceeds the health-check deadline
Migration	Deployment logs	SQL errors in `db.migrate`. The previous version remains accessible, but database changes made by the migration are not automatically undone. Check the database before correcting the issue
Running but behaving unexpectedly	App logs and access logs	See the common problems below

Common problems

I pressed Ctrl-C during deployment

Ctrl-C stops only this client’s monitoring. Deployment continues on the server and may still switch traffic to the new version. Check progress using the deploy_id shown by the CLI.

keelson status <deploy_id>

If you do not want the new version, restore the previous code after deployment completes. This command returns to a previous successful deployment whose container image is still available. Database changes are not restored.

keelson rollback --app <slug>

Static sites and SPAs do not support rollback; redeploy the earlier files. See Restore an earlier version of the code.

If you need to stop access temporarily, for example because no rollback target is available, suspend the app after deployment finishes.

keelson app stop --app <slug>

It works locally but crashes on Keelson

Configuration or storage may differ between your computer and Keelson. Ask your agent to check:

Listening only for local connections — change the listening address from localhost to 0.0.0.0.
A hardcoded port — read the PORT environment variable.
Files available only locally — examples include .env, local database files, or files excluded by .gitignore. The archive.excluded field from keelson deploy --check --json shows what was left out.
Missing environment variables — values present only in your local .env are not available on Keelson. Declare the names in secrets and register the values.
Local SQLite files — files in /tmp or the app directory do not survive restarts (/data does not exist and cannot be created). Consider migrating to Managed SQLite.

A Node app’s lockfile is rejected

Keelson’s Node builder uses npm, so pin dependencies with package-lock.json. Ask your agent to run npm install in the project root, check dependency consistency, and deploy again. Keep the generated lockfile with your source code.

You do not need to remove pnpm-lock.yaml or yarn.lock. They can coexist with package-lock.json; the build uses package-lock.json.

Data disappears

Check whether the app is storing data in files on its server. Files in /tmp and the app directory are lost on restart, redeployment, or idle shutdown. Use a database or the Files / Media SDK.

Background work does not run

Server-side work that continues after sending a response is not guaranteed to finish. In-process timers also stop when the app is stopped.

Ask your agent to finish work required by the current request before returning the response, enqueue work that continues after the response as a background task, and move recurring work to Keelson scheduled jobs. Another option is to store pending work in the database and process it with a scheduled job, but it must wait until the next run. Browser-side timers are not subject to this restriction. See When apps run.

Scheduled jobs (cron) do not run

Is the schedule more frequent than the plan’s minimum interval? Deployment rejects it.
Is the previous run still in progress? Overlapping runs are skipped.
Has the monthly execution limit been reached? Further runs are skipped for that month.
Is the app suspended?
Check the run history in Scheduled Jobs for the reason a run was skipped.

The page looks the same after an update

Your browser may have cached old files. Confirm that deployment completed, then force a refresh: Cmd + Shift + R on Mac or Ctrl + Shift + R on Windows.

Static site updates propagate gradually and may take a little time after deployment completes. If nothing changes, ask your agent to check the target app and the files that were uploaded.

A user cannot access the app

Are they a workspace member, and have they accepted their invitation?
Is their membership active, rather than deactivated?
Do they belong to a group with view permission for the app?
Are they signed in with the registered account?
Are IP restrictions denying access? The 403 page shows the source IP.

See Troubleshooting access.

No running slot available (503)

The concurrent app limit has been reached. Apps accessed within the last five minutes and apps with Priority startup occupy slots. Wait about five minutes after requests stop to an app using an unreserved slot, enable Priority startup for an important app, or upgrade your plan.

504 Gateway Timeout

This can occur when a response takes too long. Keelson allows 120 seconds for the response to begin, 300 seconds in total including streaming, and 120 seconds between streamed responses. See HTTP time limits.

Ask your agent to find the slow operation and consider shortening it, streaming results incrementally, or moving work to scheduled jobs. Streaming does not remove the time limits.

Even after a 504, the server may have completed a save or send operation. Check the result before trying again. Your implementation needs idempotency: repeated requests must not create duplicate records or messages.

A webhook returns 401 or 403

Does the path start with /api/webhooks/ or /api/external/?
For /api/external/: is the path declared in auth.endpoints, and does the method match the declaration? (/api/webhooks/ needs no declaration; methods is not applied there)
Do the token scope and allowed IPs match?

See External integrations.

Updated secrets have not taken effect

Saving secrets does not update an app that is already running. Ask your agent to apply the values too. If doing it yourself, deploy when you also have code changes, or click Apply changes in the console for value-only changes. Apply redeploys without uploading or rebuilding the code. See Apply saved values to the app.

Contact support

For a platform error such as deploy.platform.error, or if these steps do not resolve the issue, use the contact form.

Include the following to help us investigate:

Information	Where to find it
Workspace slug	`slug` in `keelson workspaces list --json`. URLs may still use a name from before a rename
App slug	`slug` in `keelson.yaml` or `keelson apps list --workspace <workspace-slug> --json`
`deploy_id`	Output of `keelson status --json` or the console’s Deploys tab
Error `code`, `message`, and `hint`	CLI output. Add `--json` to retrieve them together
Date, time, and time zone	Used to find the relevant logs
For access problems, the user’s email and the IP on the 403 page	See A user cannot access the app

Do not send app source code or secret values. If needed, support will ask for specific information.

Use the same contact form for questions about pricing, subscriptions, or invoices. See Billing and subscriptions.