---
title: Deploys
description: Fix a failed health check, a response that came from another server, or a turnzero command that is refused or stops waiting before the deploy ends.
slug: /troubleshooting/deploys
order: 2
visibility: public
redirects_from: []
---

# Deploys

Find the cause of a failed or interrupted deployment and the steps to fix it. Read this page when an upload, build, health check, or `turnzero` command fails, or when a deployment stops reporting progress.

Each entry starts from what you see: a deploy's response, `read_status`, or what the turnzero command prints. The most common problem comes first: a failed health check. When your tool shows a refusal name you do not recognize, the [refusals reference](/cloud/reference/refusals/) gives its cause and what to do next. Where the refusal includes `help`, open that address to go straight to its row. [Deploy from your computer](/cloud/getting-started/deploy-an-application/) describes each step of a deploy. [Secrets](/cloud/troubleshooting/secrets/) covers a deploy refused for a value that is not stored.

## The health check fails after about a minute with 404 responses

**Cause.** A probe is one request the health check sends to the health path. Twenty probes in a row returned 404. Your own process then responded to the [control probe](/cloud/concepts/glossary/#control-probe), so the check ended early. The manifest's `health` path is not a route your server handles, or the route is mounted after the server starts listening.

**Check.** The failed record's `detail` begins with the likely cause: no route at the [health path](/cloud/concepts/glossary/#health-check-and-health-path) responds to GET. Its `outcome.gate` shows `ended_early: true`, `answered_by: "application"`, and a `probe_sequence` of 404 runs. Run the service on your machine and request the manifest's `health` path. A 404 there confirms that no route handles the path. A 200 there points to a route mounted after the server listens.

**Remedy.** Serve the health path from the moment the server listens: 503 until the application is ready, never a 4xx, then 200. Where the route has another path, correct the manifest's `health` member and submit the manifest again. Then deploy again. [Author the manifest](/cloud/guides/author-the-manifest/#choosing-the-health-path) says how to choose the path. A server built on `node:http` can answer the path this way, `ready` set once its start-up work ends.

```js
import { createServer } from 'node:http';

let ready = false;
const server = createServer((request, response) => {
  if (request.method === 'GET' && request.url === '/health') {
    response.writeHead(ready ? 200 : 503, { 'content-type': 'text/plain' });
    response.end(ready ? 'ok' : 'starting');
    return;
  }
  response.writeHead(404, { 'content-type': 'text/plain' });
  response.end('not found');
});
server.listen(Number(process.env.PORT ?? 8080), () => {
  // Run start-up work, such as migrations, then mark the server ready.
  ready = true;
});
```

A first deploy can be refused earlier. Where the environment serves no version and no source file of the zip mentions the health path's last segment, the deploy call is refused `health_path_unserved`. Nothing is built, and no deploy is counted. The detail gives the path, cut where it is long. Write the path in the source file that serves it, or set the manifest's `health` to a path the source serves and submit the manifest. Any source file that mentions the path passes, a comment included, so a route a dependency registers passes once a comment mentions it.

This check scans source text; it does not test routes. A file mentioning the path's last segment passes though no route serves it, and the deploy's health check then fails. A route whose last segment no file spells out, such as one built from parts, is refused until a comment mentions it.

The turnzero command scans the source text before uploading. If the path is missing, it prints the same sentence and exits with status 3, without uploading anything.

To find this refusal without a deploy, call `check_deploy` with the application and run the line it returns from the application's folder. The line uploads nothing, and prints `refused: health_path_unserved` while no source file mentions the path. Run it again after each fix, until its `checked:` line counts no refusal. [Checking a deploy before you make it](/cloud/getting-started/deploy-an-application/#checking-a-deploy-before-you-make-it) describes the check.

## The health check shows connection errors while the server starts

**Cause.** A server that has not started listening responds to no probe. Failed connections, timed-out probes and 5xx responses do not count toward the twenty client-error probes that end a check early. A server that waits for migrations before listening is treated as starting. The check can still [end early if the new copy keeps stopping](/cloud/concepts/the-deploy-health-check/#when-the-check-ends-early).

**Check.** While the deploy runs toward its 180-second bound, `read_status` shows `gate_progress.last` with a 5xx `status` or an `error` such as `connection_refused`. A `timed_out` there is a probe that timed out, and the check goes on: the `summary` says it needs three 200s. A `last` of 200 can mean one or two successful probes in a row; the check needs three. The deploy's `state` reads `failed` only when the check ends. Where the check fails, `outcome.gate` keeps the new copy's console lines in `console` and its restart count in `compute`. An early end also sets `ended_early: true`.

**Remedy.** Where the server listens within the 180 seconds and the new copy does not keep stopping, do nothing: the check passes once three probes in a row return 200. A 503 or a connection error between them starts the count again. Where the check fails, read the console lines for the startup failure, such as a missing setting or a crash, and fix it. Listen on `PORT`, which a [deployed copy](/cloud/concepts/glossary/#running-copy) receives as `8080`, then deploy again.
## A deploy, promote, or restart fails its health check

**Cause.** The record ends `failed` with the outcome `health_gate_failed`. The new copy's health path did not return 200 three times in a row before the check ended, so the platform deleted the new copy. Where a version was already serving, it keeps serving with its own settings and credentials. A failed promote also leaves production's stored credentials as they were, and removes the new values it made for the new copy. A first deploy or promote that fails leaves no version serving.

**Check.** `read_status`'s `summary` gives the likely cause in a few words after `health_gate_failed`, where the evidence shows one: the status your process returned, that it stopped, or that nothing responded in time.

The failed record's `detail` gives the same cause in full, then the probes' last responses, what responded, and the new copy's restart count and last exit code.

The record's `outcome.gate` keeps the rest, the new copy's console lines in `console` among it, as [The evidence a failed check keeps](/cloud/concepts/the-deploy-health-check/#the-evidence-a-failed-check-keeps) describes. Where `console` is empty, no line had reached the platform when the check ended. Where a version was already serving, `read_logs` with the source `container` returns the new copy's later lines once they arrive. After a failed first deploy or first promote on a container app, the record keeps the only copy of the lines.

On a [pod](/cloud/concepts/glossary/#container-app-and-pod), the record keeps the check's tail. The copy's first and last lines are also kept as ended-pod lines. A later `container` read may return them marked `[pod-ended]`, as [How long console lines last](/cloud/concepts/how-log-records-arrive/#how-long-console-lines-last) explains.

**Remedy.** Fix the cause the detail gives, then deploy again. The two entries before this one cover a run of 404 responses and a server that starts slowly. A first deploy whose check fails removes the container it created. The retry creates it again and completes any provisioning step left unfinished. The platform neither reverses nor prevents what the new copy's own code did while it ran, such as a migration at start; [Add a database](/cloud/guides/add-a-database/) says how to write one. Read the failure before retrying.

## A deploy, promote, or restart ends with `pod_create_refused`

**Cause.** The record ends `failed` with the outcome `pod_create_refused` at the step `health_gate`. The platform could not start the new copy on its [pod](/cloud/concepts/glossary/#container-app-and-pod), so nothing ran to serve the health path. The health check ended once the platform had read the refusal twice in a row, not at its 180-second bound. The platform deleted the new copy, and a version already serving keeps serving.

**Check.** The failed record's `detail` says the cause is on the platform's side and gives the probe count. Your code never ran, so the record keeps no `gate` evidence and no console lines.

**Remedy.** Nothing in your application caused it. Deploy again later. Where it repeats, report it with the reference the deploy returned.

## A deploy or promote fails its smoke check

**Cause.** The record ends `failed` with the outcome `smoke_path_failed` at the step `smoke_check`. The health check passed, but a path the manifest's `smoke_paths` lists kept returning 404, a status of 500 or above, or nothing until the smoke window ended. The window is 30 seconds from the first smoke request, one for all the paths, and the check asks a failing path again every 3 seconds. The platform deleted the new copy, and a version already serving keeps serving.

**Check.** The failed record's `detail` gives the path, its last status or connection word, the new copy's restart count and last exit code, and the console's line count. The record's `outcome.smoke` holds the path's last status or connection word as `answer`, and the new copy's console lines from the first smoke request. A 404 often means the route is not mounted, has no `GET` handler, or is spelled differently in the manifest.

**Remedy.** Read the console in `outcome.smoke` for the crash. Fix the route or what it calls, such as a missing upstream key, and deploy again. Where the route has no `GET` handler, or a `GET` to it changes data, remove it from `smoke_paths` and submit the manifest again. [Checking your other routes](/cloud/concepts/the-deploy-health-check/#checking-your-other-routes) describes the check.

## A deploy is refused `database_package_outdated`

**Cause.** The manifest's package row or uploaded library copy names Database below 0.14.0. A library copy the platform cannot read is refused too where a database is declared or provisioned. The call writes no version, counts no deploy and starts no build.

**Check.** Read the refusal's detail for the old version or unreadable copy's path. The command's preparing call and `check_deploy` read only the manifest's row for this package check. `turnzero check` also reads the zip's Database package copies and notes a copy a deploy may refuse. That note counts as no refusal and does not change the check's status. Deploy and `deploy_files`, including `check_only`, also inspect the uploaded copy. A package-free application needs no Database package.

**Remedy.** [Take Database again](/cloud/guides/use-the-library/#6-take-a-newer-version) at 0.14.0 or later, replacing its copy under `lib/`. Resubmit the manifest whose `packages` rows the `library take` command regenerated, then deploy again. If the copy is unreadable, restore its complete `package.json` before retrying.

## A redeploy or promote fails its health check with too many connections for role

**Cause.** This error concerns connections on the direct port: `APP_DATABASE_DIRECT_URL`, or a version whose `APP_DATABASE_URL` still names that port. An oversized pool can leave the new copy without a connection while the old and new copies overlap. The role admits twice `connection_limit` server connections, including the pooler's and all direct clients'. A first deploy has no old copy, so it can pass with the same pool.

Through the pooled address, an oversized pool is not refused at once with this error. Transactions wait up to 15 seconds for a server connection, then fail. Long transactions can delay the health path's database read even when the client connects.

**Check.** The new copy's console shows the PostgreSQL error `too many connections for role`. Read it in the failed record's `outcome.gate.console`, or with `read_logs` and `source: "container"`. `read_status` returns `connection_limit` beside `size`: compare it with the pool's maximum in your code.

**Remedy.** Set the pool's maximum from `APP_DATABASE_CONNECTION_LIMIT`, the setting each deployed copy of an environment with a database receives, never from a number in the code. Then deploy again. After a size change, each running copy keeps its injected value until that environment's next deploy, promote or `restart_application`. Where the change re-creates production, the returned `applying` names that version; the re-creation injects the new value itself. [The connection limit](/cloud/guides/add-a-database/#the-connection-limit) explains the limit, with a pool that reads the setting.

## A deploy ends failed with the outcome `interrupted` or `slot_busy`

**Cause.** A deploy interrupted by a platform restart before its switch ends `failed` with the outcome `interrupted` within about fifteen minutes. A retry with the same artifact completes the work. A deploy fails with the outcome `slot_busy` when it cannot remove the previous container in time, or when that container is still present at the end of its wait. Nothing in your artifact causes either.

Where the application has no database, a second deploy soon after another does not wait for the earlier copy's removal, and a third waits for the oldest copy's. With a database, each deploy waits as before.

**Check.** `read_status` or `list_versions` shows the record `failed` with the outcome `interrupted` or `slot_busy`.

**Remedy.** Deploy again with the same artifact. Where the turnzero command uploaded the zip, call `deploy_command` again and run the new line it returns, because the file is deleted when its deploy ends. A deploy interrupted after its switch ends `deployed`, because the new version is already running. It needs no retry.

## The image build fails

**Cause.** The image build of the artifact failed, or ran past fifteen minutes. A failed load check is one cause of a failed image build, and every failed build is recorded the same way. [The image build fails at the load check](#the-image-build-fails-at-the-load-check) covers that cause.

**Check.** A deploy whose image build fails ends `failed` with the outcome `image_build_failed` and the step `image_build`. Nothing is applied, and a running version keeps serving. The outcome's `build` member has the build's own last lines, most often the output of `npm install`:

| Member | What it contains |
| --- | --- |
| `outcome` | `lines`, `empty` where no line was kept, or `unavailable` where the platform could not read the build's log. |
| `output_tail` | The build's last forty lines, each at most 512 bytes and 4,096 bytes in all. |
| `truncated` | True where a limit cut the lines. |
| `cause` | Present where the log was not read: `log_unavailable`, or `log_timeout` where the read ran out of time. |

The lines leave out the build service's own lines and every line mentioning a container registry, a header value, or the hosting provider. Any other address appears as `[address]`, and a credential as `[token]`. The `deploy failed` event that `read_logs` returns has the same lines.

**Remedy.** Fix the artifact, such as its `package.json` or lockfile, and deploy again. Where the detail says the build failed pulling the platform's base image, nothing in your artifact caused it: deploy the same zip again. A build the platform could not start ends `deploy_failed` instead, with no `build` member.

## The image build fails at the load check

**Cause.** After the install, the image build loads each native module file in your application that is built for Linux x64 with glibc, a dependency's or your own, on the running image. One that needs a shared library the running image does not include fails to load, and the build fails. [What the application runs under](/cloud/concepts/the-settings-a-deployed-copy-receives/#what-the-application-runs-under) describes the running image.

**Check.** The deploy ends `failed` with the outcome `image_build_failed`. The outcome's `build.output_tail` has a line of the form `load check: <file> did not load in the running image: <message>`. The line gives your own file's path under your application's folder, and a dependency's under `node_modules/`. The message most often gives the missing library. The check skips files built for another platform, such as a package's prebuilt binaries for macOS, Windows, arm64, or Alpine's musl, or for another Node.js version.

**Remedy.** Choose a package that includes the library inside its own prebuilt binary, or one written in JavaScript or WebAssembly, and deploy again. On a machine with Docker, `docker run --rm node:24-bookworm-slim dpkg -l` lists the packages of the tag's current image. The platform pins its image to a fixed digest, which can be one update behind that tag.

## The deploy stays in the image build step for a minute or more

**Cause.** The image build is the longest step of a deploy. It builds the image your version runs in from the platform's Node.js base images, installs the [artifact](/cloud/concepts/glossary/#artifact)'s dependencies with `npm install --omit=dev`, and stores the image. Where the artifact's `package.json` declares no dependency, the build can skip the install ([What the image build installs](/cloud/concepts/what-the-deploy-zip-holds/#what-the-image-build-installs)). Most of the time is the platform's own work on the image, so a shorter dependency list shortens the step only a little. Your build may also wait its turn behind other builds, and that wait counts as part of the step.

An artifact that [installs nothing](/cloud/concepts/what-the-deploy-zip-holds/#what-the-image-build-installs) and ships no [native module](/cloud/concepts/what-the-deploy-zip-holds/#native-modules) is the exception: the platform usually assembles its image without running a build, and the step takes a few seconds.

**Check.** `read_status` shows `deploy.step` as `image_build` under the deploy's environment in `environments`, and `step_started_at` says when the step began. A whole deploy typically takes up to about two and a half minutes to a development [pod](/cloud/concepts/glossary/#container-app-and-pod), and up to about three and a half to its own [container app](/cloud/concepts/glossary/#container-app-and-pod). Most of it is the image build, up to about two and a quarter minutes for an application's first version and up to about a minute and a half for a later one. Each version row's `timings` give your own figures.

Once the build has started, and not while it waits its turn, the same environment also has `build_progress`. Its `lines` are up to five of the build's newest output lines, and `read_at` is when they were read. The lines are read at most once every ten seconds, so two calls close together can return the same lines. Where they could not be read, `build_progress` has `unread` instead, and the deploy goes on.

**Remedy.** Keep waiting: call `read_status` with `wait_seconds` 45 again while `settled` is false, which means the deploy is still in flight, not that it failed. Deploying again starts nothing sooner, because another upload is refused `deploy_in_flight` and the same one returns the deploy in flight. A build that runs past fifteen minutes ends `failed` with the outcome `image_build_failed`. A build that waits fifteen minutes for its turn without starting ends `failed` with the outcome `build_wait_exceeded`, and deploying again gives it a new turn.

## A development deploy is refused with `database_not_provisioned`

**Cause.** The application's manifest declares a database, and its development environment has none. `submit_manifest` provisions the development database and `create_environment` provisions nothing, so the two calls work in either order. The database is missing only where `delete_environment` removed it and no `submit_manifest` ran since, or where a submission's database provisioning was refused.

**Check.** The response has status 409, and its `error` is `database_not_provisioned`. Nothing was written: the refused deploy used no version number and did not count toward the day's deploys. `create_environment`'s response also says to call `submit_manifest` again.

**Remedy.** Call `submit_manifest` again with the same manifest. Its response says the development database is ready. Then deploy again.

## A call is refused with `environment_not_created`

**Cause.** The application has one environment, production, and the call named development, or it called `promote`. A new application has one environment, so its deploy goes straight to production and there is nothing to promote. For development, `delete_environment` returns this refusal when no development database exists, no setup or deletion remains unfinished, and no record remains from an earlier platform version.

**Check.** The response has status 409, and its `error` is `environment_not_created`. `read_status` lists `production` alone in the application's `environments`.

**Remedy.** Name production in place of development. To put an earlier production version back, call `roll_back` with that version. To add a development environment, call `create_environment` with the application and `development`; from then on a deploy goes to development, and `promote` moves a version to production. [Manage versions and environments](/cloud/guides/manage-versions-and-environments/) describes both.

## The deploy call is refused `local_route_required`

**Cause.** Your tool's `deploy` call named `zip_sha256`, which only the [turnzero command](/cloud/concepts/turnzero-command/) sends. Nothing was prepared.

**Check.** The response has status 409, and its `error` is `local_route_required`.

**Remedy.** Call `deploy_command` with the application, without an `environment` member, then run the line it returns once, from the application's folder, as [Build and upload the artifact](/cloud/getting-started/deploy-an-application/#3-build-and-upload-the-artifact) describes.

## The upload is refused `upload_hash_mismatch`

**Cause.** The upload [grant](/cloud/concepts/glossary/#transfer-grant) accepts only the zip whose hash the command gave when it prepared the upload. The zip sent has another hash. The command always sends the zip it hashed, so this comes from a client of your own that sent other bytes.

**Check.** The upload or the start was refused with the `error` `upload_hash_mismatch`. A refused upload wrote nothing.

**Remedy.** Start again: from your tool, call `deploy_command` with the application, without an `environment` member, and run the line it returns.

## A deploy returns `manifest_notice`, or it is unclear which manifest a deploy runs under

**Cause.** A deploy runs under the manifest `submit_manifest` recorded. The project's `manifest.json` in the zip is only compared with it, so an edit to the file changes nothing until it is submitted.

**Check.** The deploy's answer, or the command's `started:` line, includes `manifest_notice` naming the members that differ. `submit_manifest`'s answer says which manifest counts in `deploy_reads`.

**Remedy.** From your tool, submit the edited manifest with `submit_manifest`, then deploy again. [Author the manifest](/cloud/guides/author-the-manifest/#a-manifest-that-works) and [What the deploy zip holds](/cloud/concepts/what-the-deploy-zip-holds/) say more.

## The command returns `transfer_grant_spent` or `transfer_grant_expired`

**Cause.** The command uploads and starts under a short-lived upload grant, which allows one upload and one start, and expires five minutes after the call that prepared it. A later call that prepares an upload replaces one that has not started. [Transfer grant](/cloud/concepts/glossary/#transfer-grant) describes the grant.

**Check.** The command's response has status 403, and its `error` is `transfer_grant_spent` or `transfer_grant_expired`. Its `detail` says which case you are in. Where it says the bytes were not written, another write under the grant spent it first. Where it gives a version, the first run's start deployed that version. Where it says the upload was replaced, a later line prepared another upload.

**Remedy.** Where the `detail` gives a version, read that deploy with `read_status`; nothing needs to run again. Where a later line replaced the upload, follow that line's run instead. Where `read_status` shows the earlier upload as the `pending_upload` of the deploy's environment, with a `retry`, make that call, which starts it with no new upload. Otherwise call `deploy_command` with the application, without an `environment` member, run the line it returns at once, and make its `next` call. Run a new line only once the earlier run has ended, because the new line prepares an upload that replaces the earlier one.

## The command prints a refused start

**Cause.** The zip uploaded, and one of the deploy's checks refused the start, such as the application's `deploys-per-day` limit or a deploy already in flight, or the upload grant expired before the start. Nothing was deployed, and that grant starts nothing more.

**Check.** The command printed the upload's response, then a refusal whose `error` gives the check, and its `detail` says what to do. `read_status` shows the `pending_upload` of the environment the deploy goes to, with `state` `refused` and that refusal, or `not_started` after an expiry.

**Remedy.** Where the cause lies outside the zip, clear it, then make the `retry` call that the refusal's detail or `read_status`'s `pending_upload` gives. It starts the same zip again. Where the zip itself was refused, such as `artifact_layout_invalid`, fix the folder, call `deploy_command` again, and run its new line.

## The authorize line is refused `token_code_refused`

**Cause.** The token request or one-time [token code](/cloud/concepts/glossary/#token-code) the line names cannot be used. A verifier is a random secret the command keeps on this computer. The platform checks it against the challenge the command printed earlier.

For `turnzero authorize --mint <id>`, the token request is unknown, expired, or already claimed, or this computer's verifier did not match it; a verifier that does not match leaves the token request unused. For a line that pipes a code, such as `token claim`'s, the code is unknown, expired, or already presented, or its verifier did not match. The account may also be suspended, or the session that minted it may have ended. The refusal is the same in every case and does not say which.

**Check.** The command printed a refusal under `exchange`, with status 403 and the `error` `token_code_refused`. Nothing was minted.

**Remedy.** The simpler way is `turnzero login`, run in a terminal of your own. It authorizes this computer with no `mint_token` call ([Authorize this computer for deploys](/cloud/getting-started/connect-your-tool/#authorize-this-computer-for-deploys)). Where your tool authorized the computer instead, it repeats its own steps. Call `mint_token` again with the challenge the turnzero command printed, and run the line it returns once.

A code lasts five minutes by default, so run the line soon after the call. Where you did not run the line yourself, `list_tokens` shows each token by its label, and `revoke_token` ends one you do not know.

## The deploy line prints a `mint_token` call

An older turnzero command prints this; the current command prints the sign-in route, the next entry.

**Cause.** The computer holds no live token for the platform's address, and `TURNZERO_CLOUD_MINTED_TOKEN` is not set. The line holds no credential, so the command sent nothing ([The turnzero command's credential](/cloud/concepts/how-the-turnzero-command-finds-its-credential/)).

**Check.** The command printed two routes, then `challenge:` and a `mint_token` call, and ended with status 3.

**Remedy.** Follow [Ways to deploy to Turn Zero Cloud](/cloud/getting-started/ways-to-deploy/). For regular work with a usable command, a signed-in tool makes that `mint_token` call, runs its returned authorization line, then repeats the deploy line.

Use the command for an app the person will keep, starting with its first deploy wherever the command works. A first simple test app the person will discard can use `deploy_files` within its limits when it needs no binary files, scaffolding, or local runs.

If the command cannot work, use the fallback routes in the next entry.

If a step can't run here, the AI tool tries another available in-tool route first and tells you which route it chooses and why. Only when none can complete the deploy does it give you that exact step to run once in your own terminal, then wait for the result. It suggests no permission change.

A tool connected by a minted token, or a job, sets `TURNZERO_CLOUD_MINTED_TOKEN` from where its token is kept, never by writing the value in a line. If the token was minted at an address other than https://turnzero.ai, the tool or job also sets `TURNZERO_CLOUD_ORIGIN` to that address. It cannot make the `mint_token` call, since that takes a sign-in alone. It sets them for that line alone, as [Setting the variable for one line](/cloud/concepts/turnzero-command/#setting-the-variable-for-one-line) shows. [Authorized computer](/cloud/concepts/glossary/#authorized-computer) describes the token a signed-in tool's line keeps.

## The deploy line prints the sign-in route

This is what the current turnzero command prints; an older command prints the `mint_token` call, the entry above.

**Cause.** The computer holds no live token for the platform's address, and `TURNZERO_CLOUD_MINTED_TOKEN` is not set. The line holds no credential, so the command sent nothing ([The turnzero command's credential](/cloud/concepts/how-the-turnzero-command-finds-its-credential/)). Signing in to the MCP connection connects your tool and signs no computer in, as [Authorize this computer for deploys](/cloud/getting-started/connect-your-tool/#authorize-this-computer-for-deploys) says.

The command returned by `check_deploy` needs the same credential: `TURNZERO_CLOUD_MINTED_TOKEN` when set, otherwise this computer's token for the line's origin. Without one, it prints the same sign-in routes and sends nothing. After authorization, run the same check line again before deploying.

**Check.** The command first names the `TURNZERO_CLOUD_MINTED_TOKEN` route, then lists the same routes as `turnzero whoami`. Each listed route starts with what it needs. The person's sign-in instructions and `login` line follow the list. The command then tells your AI tool to try the available routes before handing a step to you. It ends with status 3.

**Remedy.** Your signed-in AI coding tool follows [Ways to deploy to Turn Zero Cloud](/cloud/getting-started/ways-to-deploy/). For regular work, it [authorizes this computer](/cloud/getting-started/connect-your-tool/#authorize-this-computer-for-deploys), then runs the same printed deploy line again, unchanged. It needs no fresh `deploy_command` call to obtain another line. Running it "once as given" means once per attempt, without rewriting it.

Use the command for an app the person will keep, starting with its first deploy wherever the command works. A first simple test app the person will discard can use `deploy_files` within its limits when it needs no binary files, scaffolding, or local runs.

If the command cannot work, the tool uses `deploy_files` within those limits and the upload route past them or for a file it cannot carry. For upload, it calls `declare_storage_area` if needed, uploads a ZIP with `mint_upload_grant`, then calls `deploy` naming the upload as `artifact` ([Upload steps](/cloud/guides/store-files/#an-upload-grant-from-your-tool)).

Both `login` and the returned `authorize --mint <id>` line print `authorized:` on success, followed by the platform's address, the token's label and its expiry. Where the account was read, the line names it too. The label comes from this computer's host name, with characters the label cannot hold removed and the length bounded; a fallback name is used if nothing remains. `list_tokens` shows the token under that label.

If no in-tool route works and you need to authorize this computer yourself, run the printed `login` line in your terminal and approve the sign-in in the browser. Once `login` prints `authorized:`, your tool runs the deploy line again. You can also use `login` to renew your own sign-in.

If a command can't run here, the AI tool tries the remaining available routes first and tells you which route it took and why. If none works, it gives you that exact command to run once in your terminal and waits for the result. It never rewrites the command to make it run.

A tool connected by a minted token, or a job, sets `TURNZERO_CLOUD_MINTED_TOKEN` from where its token is kept, never by writing the value in a line. If the token was minted at an address other than https://turnzero.ai, the tool or job also sets `TURNZERO_CLOUD_ORIGIN` to that address. It sets them for that line alone, as [Setting the variable for one line](/cloud/concepts/turnzero-command/#setting-the-variable-for-one-line) shows. Such a tool cannot sign in this way, and cannot call `mint_token`, which takes a sign-in alone. [Authorized computer](/cloud/concepts/glossary/#authorized-computer) describes the token a signed-in tool's line keeps.

## The command ends with status 3

**Cause.** The command started nothing. It refused a Node.js older than 24, an option, the folder, a line naming another application than the folder's `manifest.json`, or a computer holding no token for the origin.

Or the application check before the zip was refused, redirected, unanswered, or failed. Each of those endings gives status 3, with no zip built and nothing started; the command follows no redirect. Or the platform refused the call that prepares the upload, the upload, or the start, or the upload got no response. Or no file of the zip mentions the health path a first deploy checks, so the command stopped before the upload.

**Check.** The command ended with status 3, and its last lines name the cause. The [turnzero command reference](/cloud/reference/turnzero-command/#deploy) lists each cause under `turnzero deploy`.

**Remedy.** Follow the printed refusal or sentence. Where no source text gives the health path, follow [the 404 entry's remedy](#the-health-check-fails-after-about-a-minute-with-404-responses). Where the folder had no `package.json` at its top, run the line from the application's folder, or give that folder as `local_path` in a new `deploy_command` call. Where the command read no credential, follow the remedy of the entry above on what the deploy line printed: the sign-in route or a `mint_token` call.

## The line is refused because manifest.json names another application

**Cause.** The folder's `manifest.json` binds it to an application through its `application` member, and the line's `--application` gives another, or the member is not an application id. A copied project, or a folder deployed before to another application, has such a member. The command stopped before it zipped the folder or sent anything ([The folder's application](/cloud/concepts/the-manifest/#the-folder-s-application)).

**Check.** A deploy or check line printed one line opening `manifest.json binds this folder to application`, or saying the member is not an application id, and ended with status 3. Nothing was uploaded.

**Remedy.** Your tool asks the account's owner which application the folder is for, as the refusal's last sentence says. Where it is the one the manifest names, deploy with a line naming that application. Where the owner means the folder for the line's application, change or remove the `application` member, then run the line again. A tool changes the member only on the owner's word, because the check is what stops a deploy to the wrong application.

An installed turnzero command older than 0.19.0 refuses `--application` on a `scaffold` line as an unknown option, with status 3 and nothing written, because `scaffold` makes no check for a newer version. Run `npm install -g turnzero` to update it, or scaffold without the option and let the first deploy bind the folder.

## The deploy line cannot reach the platform

**Cause.** The environment where your tool runs code cannot reach `turnzero.ai`. Its signed-in MCP connection may still reach the platform.

**Check.** npm cannot fetch the command, or the command cannot connect: the line ends with a 403, `ENOTFOUND`, `ECONNREFUSED`, or a timeout, before any `prepared:` line.

**Remedy.** Use `deploy_files` through your signed-in MCP connection, as [Deploy from a chat](/cloud/getting-started/deploy-an-application/#deploying-from-a-chat-whose-shell-cannot-reach-the-platform) describes. Inline files are limited to 512 KiB each. For a binary file you cannot read, ask the person to [upload it from the application's page](/cloud/guides/store-files/#upload-a-file-from-the-application-s-page), then use a stored entry. Stored entries have no per-file cap, but count toward the same 4 MiB total and 200 entries.

Beyond those limits, use the command where it works, otherwise the [ZIP upload route](/cloud/getting-started/ways-to-deploy/). With no shell, ask the person to deploy from a computer with one. If the MCP connection also cannot reach the platform, ask the person to restore that access.

## A `deploy_files` file is refused `deploy_files_syntax_error` on a line that looks correct

**Cause.** A tool call's arguments are JSON, and a JSON escape in a string arrives as the character it names. So `\u2028` or `\u2029` in a file's `content` arrives as a real line separator or paragraph separator. JavaScript reads both characters as line ends, so a regular expression literal that holds one ends there.

**Check.** The response has status 422, and its `error` is `deploy_files_syntax_error`. Its `detail` names the path, the line, and the column, on a line where your file means to hold `\u2028` or `\u2029`, often with `Unterminated regular expression`. The `detail` also names the separator it met by code point and column, such as `the line holds U+2028 at column 19`.

**Remedy.** To send the six characters `\u2028`, escape the backslash in the argument: `\\u2028`, and `\\u2029` likewise. Then send the file again as the `detail` says.

## A `deploy_files` hash does not match, or a file stays `missing`

**Cause.** The platform keeps each file's text byte for byte, under the SHA-256 of what it received. A hash your tool computed over its own copy differs where the two copies differ. Most often that is the line endings, CRLF or LF, a trailing newline, or a byte-order mark. A file also stays `missing` once the platform stops keeping it. That can happen a day after you sent it, where no version that either environment serves or is deploying was deployed from a list naming it.

**Check.** The response has status 409 and the `error` `deploy_files_hash_mismatch`, and its `detail` names the hash received. For a list entry, `refused` gives it as `received_sha256`. Or a list naming the file by `sha256` alone answers `awaiting_files`, the file under `missing`.

**Remedy.** Send the file with its `content` and no `sha256`. The answer's `kept` gives the hash the platform computed, and a later list names the file by it. A `check_only` call's `kept` gives every file's hash the same way.

## A deployed file holds a byte-order mark yours does not

**Cause.** A tool call's arguments are JSON, so the six characters `\uFEFF` in a file's `content` arrive as one character, U+FEFF, the byte-order mark. The deployed file then holds that character where your file holds the escape.

**Check.** The answer carries `content_notice`, naming the file and the line that holds U+FEFF. The file's `sha256` under `kept` differs from the hash your tool computes for its own copy.

**Remedy.** To send the six characters `\uFEFF`, escape the backslash in the argument: `\\uFEFF`, keeping the escape's letters as your file writes them. Then send the file again.

## A refused line reports status 0 or 1

**Cause.** The command ended with its own status, but the shell your tool ran it in reported another. A PowerShell process started with `-Command` ends with 1 for any status but 0. Where another statement follows the line in the same process, it ends with that statement's status, often 0.

**Check.** The line's last printed lines name a refusal, such as `Nothing was uploaded and nothing was started.`, while your tool reports status 0 or 1.

**Remedy.** Read the status right after the line, in the shell that ran it: `$?` in bash and zsh, `$LASTEXITCODE` in PowerShell after `turnzero.cmd`, and `%ERRORLEVEL%` in cmd. Then follow the entry for that status.

## The command stops waiting before the deploy ends

**Cause.** After its start, the command waits for the deploy and reads its progress under its upload grant. It stops where a progress read was refused or got no response, and your tool may stop it first where it limits how long a shell command runs. A progress read is refused `progress_window_ended` once its window has passed: five minutes after the deploy ends, and never later than fifteen minutes after the start. It is refused `account_suspended` while the owning account is suspended. A read gets no response where its connection drops, or where it stalls past 60 seconds.

**Check.** The command printed any refusal it received and a sentence that mentions `read_status`, and it ended with status 2. Where your tool stopped it, the output ends at a step line with no outcome line.

**Remedy.** The deploy continues: call `read_status` with the application, the environment the deploy goes to, and `wait_seconds` 45, or fewer where your tool gives a call less time, until `settled` is true. Next time, allow the command the time [What it prints](/cloud/concepts/what-the-turnzero-command-reads-and-prints/#what-it-prints) gives. Where your tool stops a shell command sooner, run the line as a background job, or, where your tool has no background job, set `TURNZERO_DEPLOY_NO_WAIT` in the shell so it returns after the start.

## A deploy, promote, or rollback call gets a response from something other than the platform

**Cause.** A server between your tool and the platform responded in its place, with its own error page such as a 502, or the connection closed first. The action your call started may still have run. Such a response says nothing about whether it did.

**Check.** The response is not the platform's JSON body: it is an HTML page, an empty body, or a connection error.

Call `read_status` with the application, the environment, and `wait_seconds` 45. The `environments.<name>.deploy` member shows the named environment's latest row. The action started only where the row's `kind` matches it and its `started_at` is later than your call. A rollback's row is a `"promote"`, and a restart's is a `"restart"`. A `deploy_files` call that starts a deploy records a `"deploy"` row. The row's `version` is the version the action deploys or promotes, and `started_at` is the platform's clock, not your tool's. An upload that `pending_upload` still lists was not started.

**Remedy.** Where the action started, do not repeat it: follow it with `read_status` until `settled` is true. Where `pending_upload` still lists the upload, make the call its `retry` gives. Repeat any other call only where the read shows it did not start. That holds for a `deploy_files` list call too: send the list again only where the read shows no deploy started after it. Where the read cannot show which, do not repeat it: call `list_versions`, or ask the account's owner. For `run_schedule`, call `read_schedules` instead, and repeat the call only with the same `request_id`.

## The image build is refused before it starts

**Cause.** Before an image build starts, the platform reads its two base images, the one your version runs on and the one it builds dependencies on. Where it could not read one, it refused the build. Nothing in your artifact causes this.

**Check.** The deploy's record is `failed`, and its `outcome` has the `error` `deploy_failed` and no `build` member. Nothing was built or applied, and a running version keeps serving. The `detail` gives the version number in one of two texts:

- `The image build of version <n> was refused before it started: the platform's base image could not be read, and a retry may go through.`
- `The image build of version <n> was refused before it started: the platform's base image is unavailable, and the platform has recorded it; a retry goes through once it is restored.`

**Remedy.** Where the detail says a retry may go through, deploy again. Where it says the platform has recorded it, nothing in your artifact needs to change: the platform's staff restore the image, and the platform sends you no message. Deploy again later and read that deploy's outcome.

## A deploy fails with `deploy_failed` and a short detail

**Cause.** A step the platform runs for your deploy or promote failed in a way no named refusal describes. The hosting provider refused a call, a connection failed, or one of the platform's own steps failed. Nothing in your artifact causes this.

**Check.** The record is `failed`, its `outcome` has the `error` `deploy_failed`, and `step` gives the step where it stopped. The `detail` takes one of four short forms, and never includes the provider's message or the platform's internal names:

- `The image registry was busy (http_<status>)`, followed by what to call again: the platform could not fetch your application's image, and has already tried once more.
- `refused by the provider (http_<status>)`: the hosting provider refused a call with that status.
- A connection failure with its code, such as `fetch failed (ECONNRESET)` or `the connection failed (ECONNREFUSED)`: the platform could not reach a service it calls.
- `failed (error)`: one of the platform's own steps failed.

**Remedy.** Deploy or promote again, because a passing fault often clears. Where the same detail comes back, report it with the `reference` that the call returned. Staff read the full text under that reference. A promote made with `turnzero promote` prints that reference on a `reference:` line.

## A promote or production deploy fails with `server_unavailable`

**Cause.** The first promote after the manifest declares a database, or the first deploy to production of an application with one environment, sets up the production database, and no database server could take it.

**Check.** The record is `failed`, its `outcome` has the `error` `server_unavailable` and the `step` `database_pair`. The same step can fail with `cell_not_configured`.

**Remedy.** Follow the row for your refusal in [Add a database's refusals](/cloud/guides/add-a-database/#refusals). Where the `detail` gives an earlier run, report it, and the next promote or deploy goes through once the platform's staff have cleared it. Where it gives none, try again later. On an application with one environment each try is a whole deploy. Deleting the application with `delete_application` also removes the earlier attempt's setup, with all of the application's data, so it is a choice only for an application that has never served production.
