Deploys #
On this page
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 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 describes each step of a deploy. 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, 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 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 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.
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 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.
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 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 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, 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 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 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, 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 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 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 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 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 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'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). 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 and ships no native module 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, and up to about three and a half to its own container app. 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 describes both.
The deploy call is refused local_route_required #
Cause. Your tool's deploy call named zip_sha256, which only the 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 describes.
The upload is refused upload_hash_mismatch #
Cause. The upload 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 and 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 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 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). 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).
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. 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 shows. 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). Signing in to the MCP connection connects your tool and signs no computer in, as 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. For regular work, it authorizes this computer, 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).
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 shows. Such a tool cannot sign in this way, and cannot call mint_token, which takes a sign-in alone. 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 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. 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).
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 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, 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. 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 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)orthe 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. 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.