Troubleshooting
Start by asking your agent:
Get this app’s current Kyno status and recent deployment events. Explain the last failure in plain language before changing anything.
Kyno does not appear in the agent
Section titled “Kyno does not appear in the agent”- In Codex, run
codex mcp listor type/mcp. - In Claude Code, run
claude mcp get kynoor type/mcp. - Confirm the URL is exactly
https://console.kyno.work/mcp. - Complete the browser OAuth flow with Google or an email magic link.
The Dockerfile is missing
Section titled “The Dockerfile is missing”Kyno requires a file named Dockerfile at the project root. Ask the agent to create the smallest production Dockerfile for the application.
The app never becomes ready
Section titled “The app never becomes ready”The final process must listen on 0.0.0.0:$PORT. Binding to 127.0.0.1, using a fixed development port, or exiting after startup will fail the readiness check.
A sleeping app briefly says it is not ready
Section titled “A sleeping app briefly says it is not ready”The first authenticated request wakes a sleeping app. Kyno waits up to 15
seconds for startup; if the app takes longer, that request returns 503 while
the start continues. Wait a few seconds and refresh. If repeated requests still
fail, inspect the app’s current status and recent events—the start may have
failed for the same reasons as a new deployment.
See App sleep and wake for the full lifecycle.
The build is too large
Section titled “The build is too large”The final image must fit within 512 MB. Remove build-only files, caches, browsers, large system packages, and development dependencies from the final image.
Data disappears after a restart
Section titled “Data disappears after a restart”Only /data is persistent. Move SQLite files and user-generated files there. Use the provided DATABASE_URL rather than a database path inside the application directory.
A secret change has no effect
Section titled “A secret change has no effect”Variables and secrets are injected when the app starts. Restart the app after calling set_variables or set_secrets.
A teammate cannot open the app
Section titled “A teammate cannot open the app”Check People in the Kyno console. The person must be a current workspace member and must sign in with the exact email address that received the invite. If the workspace invitation expired, an owner or admin can send a new one.
A monorepo deploys only one service
Section titled “A monorepo deploys only one service”This is expected. Kyno runs only the root Dockerfile’s final image. Put the required frontend and backend in that image, or deploy separately required services as separate apps.
Do not work around a failed deploy by uploading .env. Pass non-sensitive values as variables and credentials as write-only secrets.