---
title: Manage versions and environments
description: Roll production back, read the version history, halt, resume, or restart an environment, rename an application, or delete it or its development environment.
slug: /guides/manage-versions-and-environments
order: 25
visibility: public
redirects_from: []
---

# Manage versions and environments

Prompt:

> Checkout broke with the last release. Roll production back to the version before it.

Also works:

- "What did we deploy this week?"
- "Stop the development environment for now."
- "Rename this application to parts-search."
- "Delete the test application."

Your AI tool rolls production back with `tzcloud_list_versions` and `tzcloud_roll_back`. A rollback restores the earlier version's code, setting bindings and plain values, never data ([Roll back](#roll-back)). It halts, resumes, or restarts an environment with one call each. The signed-in site also offers **Pause app** and **Resume app** ([Halt and resume](#halt-and-resume)). A rename or a deletion waits for your approval in the browser.

## What your AI tool does

- For a rollback, reads the `release` [skill](/cloud/concepts/glossary/#skill) (`read_context`, id `skill:release`) and follows it. It rolls back only when you say so.
- Calls `tzcloud_list_versions` when you ask what was deployed, narrowed to one environment if you name one.
- Before halting production, [asks for your yes unless you already asked](#halt-and-resume). Calls `tzcloud_halt_environment` to halt an environment, the same tool with `resume: true` to resume it, or `tzcloud_restart_application` to restart it. Each runs without a separate approval page. The signed-in site's **Pause app** and **Resume app** controls make the same halt and resume actions ([Halt and resume](#halt-and-resume)).
- For a rename or a deletion, calls `tzcloud_rename_application`, `tzcloud_delete_environment`, or `tzcloud_delete_application` and prints the approval link in the response. After you approve in the browser, it reads the outcome with `read_approval_status`.
- Asks you for a browser approval only for those three [destructive-tier](/cloud/concepts/glossary/#management-action-tier) actions.
- Reports the version production serves, the environment's `halted` member, or the [pending action](/cloud/concepts/glossary/#pending-action)'s outcome, and writes nothing into your project.

## What you need

- For renaming or deleting an application, sign in to a browser with the same account, because you approve that action there yourself.

## Before your AI starts

**For the AI tool:** Check the following before starting.

- Your AI tool connected and signed in ([Connect your AI assistant](/cloud/getting-started/connect-your-tool/)).
- An application deployed as [Deploy from your computer](/cloud/getting-started/deploy-an-application/) describes. A rollback needs an earlier deployed version that production does not serve.
- For a production halt, your signed-in session or a [token](/cloud/concepts/glossary/#minted-token) minted for the whole account.

## Steps

Each section below is one task, and they do not depend on each other. A rollback is the one most often needed, so it comes first.

### Roll back

Your AI tool calls `tzcloud_list_versions` for production to find the version production served before.

```json
{ "application": "<application id>", "environment": "production" }
```

The response lists the rows newest first. The row with `serving: true` is the version production runs now. The version to roll back to is an earlier deployed row whose `promotable` is true. Your AI tool then calls `tzcloud_roll_back` with that version and `wait_seconds`, so the response waits until the rollback ends.

```json
{ "application": "<application id>", "version": 41, "wait_seconds": 45 }
```

A rollback [promotes](/cloud/concepts/glossary/#promote) the version you name. Like every promote, it reuses that version's image and creates a new production [platform credential](/cloud/concepts/glossary/#platform-credential). The database credential stays the same. It takes `wait_seconds`, 1 to 45, as a promote does ([Promote to production](/cloud/guides/turn-on-development-and-promote/#promote-to-production)). The response then waits until the rollback ends, and returns status 200 with `state` `deployed` or `failed` and the record's `outcome`.

Without `wait_seconds`, or where the wait runs out, it returns status 202 with `state: "deploying"`. Either response also includes `next`: the exact `tzcloud_read_status` call that follows the rollback until it ends. That call names `environment: "production"`, so its top-level members describe production.

When a rollback shows `deployed`, every router already sends production's hostname to the version you named. The switch waits until the rollback is 10 seconds old, and the record turns `deployed` 3 seconds after it. So a rollback takes at least 13 seconds. The response's `summary` and `detail` say how it ended, and its `health_path` is the path the [health check](/cloud/concepts/glossary/#health-check-and-health-path) probes on the version you named.

A response that is not the platform's own, such as a gateway's error page or a closed connection, says nothing about whether the rollback was made. Read `tzcloud_read_status` first: a rollback that started shows as a `"promote"` row begun after your call. Roll back again only where none did.

`tzcloud_roll_back` works on every application, including one with a single environment, where `tzcloud_promote` itself is refused. There every deploy goes straight to production, so the version you name is one of production's own earlier deploys.

A rollback to production's serving version is [refused](/cloud/concepts/glossary/#refusal) 409 `version_already_serving`. A newer version is refused 409 `version_newer_than_serving`; use `tzcloud_promote` on an application with two environments, or deploy that code again on one. A number that no deployed row has is refused 404 `no_such_version`. A version whose image the platform has deleted is refused 409 `version_image_pruned`; deploy its [artifact](/cloud/concepts/glossary/#artifact) again as a new version instead. While production is halted, a rollback is refused 409 `target_environment_halted`.

A rollback restores the earlier version's code, setting bindings and plain values. The platform takes no copy of your data at a promote. So where the rollback crosses a change to your data model, you decide yourself how to migrate or restore the data. The platform does not provide a migration tool. Its reserved HTTP action `apply_migration` returns 501 `not_yet_provisioned`. [What a promote does to production's database](/cloud/guides/turn-on-development-and-promote/#what-a-promote-does-to-production-s-database) explains what the [migration walk](/cloud/concepts/glossary/#migration-walk) does when the version starts.

### The version history

`tzcloud_list_versions` returns the application's history newest first, one row per deploy, promote, restart, or [platform redeploy](/cloud/concepts/glossary/#platform-redeploy). An optional `environment` limits the response to one environment, and `limit` and `cursor` split it into pages. On every page, the response's `serving` names the number of the version each environment serves. `tzcloud_read_status` also names it, without the history. The [`tzcloud_list_versions` reference](/cloud/reference/actions/list-versions/) lists each row's members.

Two members say what a row can be used for:

- `serving` is true on the row of the version each environment runs.
- `promotable` is true on a deployed row whose image the platform still keeps, so `tzcloud_promote` and `tzcloud_roll_back` can name its version. It says the image still exists, not that promoting it is advised.

The platform keeps the images of each environment's twenty most recent deployed versions, the serving version among them, and deletes older ones once a day. A row whose image was deleted shows `promotable: false`, and a promote or rollback of its version is refused 409 `version_image_pruned`. The history leaves out the rows of a deleted environment.

Two more members describe the [runtime harness](/cloud/concepts/glossary/#runtime-harness), the platform's code built into every image beside your application. `harness_hash` is the SHA-256 of the harness in the row's image, or null where the platform did not record it. `harness_current` is true where that harness is the one the platform builds into new images today. Only a new deploy gives a version the current harness, because a promote reuses the image as it is.

`artifact_hash` is the deployed ZIP's SHA-256, which `turnzero hash` in the application's folder reproduces from unchanged deployable files on the same Node.js version after a deploy through the command. If the first deploy adds `application` to `manifest.json` after making its ZIP, the folder's hash then differs; subsequent deploys include that member. For a serving version, `kept` lists file paths and hashes only when `tzcloud_deploy_files` supplied its files, and is null for other deployment routes.

A rollback and a promote both write a `"promote"` row with the number of the version they promote. On an application with one environment, each deploy writes a production row of kind `"deploy"`. So the history shows which version production served, and when. [The version history](/cloud/concepts/applications-and-environments/#the-version-history) explains how the serving version is determined.

A restart writes a `"restart"` row with the number of the version it restarted, so a `"deploy"` row and a `"restart"` row can carry the same number. `kind` tells them apart, and both name the same image, so promoting that number promotes that image.

Each ended row's `outcome` starts with `result`: `succeeded`, `failed`, `interrupted`, or `superseded`. Each row's `timings` lists the steps it went through, with when each began and ended.

`succeeded` means the declared health path answered 200 three times in a row within the check's time limit. On a deploy, and on a promote of a version production did not serve at the time, the manifest's smoke paths also passed. Where the row replaced a serving version, the routers' short wait after the switch has also passed.

No other path is checked, so a failing route shows in `tzcloud_read_status`'s `server_errors` once a request reaches it. A single request ended with `upstream_ended` (the router's answer when the application's own process ends before it responds) just after a switch may be retried where repeating it is safe.

After a failed first promote, or a failed first deploy of an application with one environment, production has no serving version. `tzcloud_list_applications` and `export_account` then return the application's own `state` as `failed`, the same value production's environment shows. The application page on the signed-in site shows it as Failed to reach production. Once a promote or a production deploy succeeds, the state is `deployed`. A promote or deploy that fails while a version is serving leaves the state `deployed`.

### Deploying a new version

Deploy the new build with `turnzero deploy`, following [step 3](/cloud/getting-started/deploy-an-application/#3-build-and-upload-the-artifact) with a new build, followed by the `tzcloud_read_status` wait of [step 5](/cloud/getting-started/deploy-an-application/#5-read-the-status). On an application with two environments, a promote then moves the new version to production. A new deploy is also how a version gets the platform's current runtime harness, because its image is rebuilt. A version-history row of kind `restart` is not a new deploy: it restarts the running copy from the same build.

A development deploy gives the new copy the same development platform credential and creates no new one.

### Restart an environment

`tzcloud_restart_application` re-creates the environment's [running copy](/cloud/concepts/glossary/#running-copy) from the version it serves, under the platform's current settings. Use it after you rotate a secret, so the running copy gets the new value. It builds nothing and writes a `restart` row for the same version. It does not count against the application's deploys per day.

```json
{ "application": "<application id>", "environment": "production", "wait_seconds": 45 }
```

With `wait_seconds`, 1 to 45, it returns once the restart ends, as a promote does; otherwise it returns status 202 at once. Without `wait_seconds`, or where the wait runs out, its `next` is the `tzcloud_read_status` call for the restarted environment. It is refused while a deploy, promote, or restart of the environment is in progress. The HTTP action route's `store_secret` call with `replace: true`, a new `value`, and `restart: true` under your own bearer token starts the same restart. It restarts the environment whose running copy holds the old value ([Store a secret](/cloud/getting-started/store-a-secret/#3-replace-a-value)).

Each response includes `health_path`, the current manifest's health path, which the restarted copy's health check probes. Like a rollback, a restart switches no sooner than 10 seconds after it starts and shows `deployed` 3 seconds after its switch. Its `finish` step holds the restart until then, so a copy that is ready early waits there, and its `switching` step is those 3 seconds.

A restart drops no request when it switches. The old copy keeps running for about 15 seconds after the switch, while the routers move to the new copy. Where it runs as a container, its log lines are marked `[retiring]` ([Read logs and counters](/cloud/guides/read-logs-and-counters/)). When the old process ends, each request it holds that has no response header yet is cut off: the caller gets 502 `upstream_ended`, and the `router` source records it.

A response that is not the platform's own, such as a gateway's error page or a closed connection, says nothing about whether the restart was made. Read `tzcloud_read_status` first: a restart that started shows as a `restart` row begun after your call. Restart again only where none did.

A restart re-applies the [settings](/cloud/concepts/glossary/#setting) the manifest bound when the running copy was made, each with the value stored now. A rollback re-applies the bindings its version last had in production, or those its deploy recorded where production never ran it ([Changing the manifest](/cloud/concepts/the-manifest/#changing-the-manifest)).

A bound setting is left out where its stored name no longer exists or a later rule rejects it. The application's log then shows a warning. The restart or rollback is never refused for it. Where the secret store does not return a value, the restart or rollback ends as failed with `bound_setting_unreadable` before anything is applied, and the serving copy is unchanged; try it again.

So a restart brings a rotated bound value into a running copy that already has the binding. A binding added since the copy was made waits for the next deploy or promote ([Store a secret](/cloud/getting-started/store-a-secret/#bind-a-value-to-a-setting)). `tzcloud_read_status` reports these cases for each environment:

- `rotated_since_read` lists each setting whose secret was stored or rotated after the running copy started, which a restart brings up to date.
- `bound_not_applied` lists each setting the manifest binds that the running copy lacks, which only the next deploy or promote applies. It also lists each plain setting whose value in the manifest the running copy lacks, by its name alone and never with the value.
- `settings_mismatch` lists each secret whose stored value differs from the value the running copy received. The platform compares two fingerprints, short codes it makes from each value with a key of its own. An entry reads `different`, which a restart applies, or `not_comparable`, where the two fingerprints were made with different keys ([The running copy seems to use the old value](/cloud/troubleshooting/secrets/#the-running-copy-seems-to-use-the-old-value-after-a-rotation)).

The response's `summary` counts the settings in each of the first two lists and names the list. It does not repeat the settings. Where either of those lists has an entry, or a name in `settings_mismatch` reads `different`, the environment's `settings_apply` says which action applies each list.

The lists are computed at every read. So an empty `rotated_since_read` means the running copy has the stored value of every setting it applied, never that the platform has not looked yet. [Check that a rotation reached the running copy](/cloud/getting-started/store-a-secret/#check-that-a-rotation-reached-the-running-copy) gives the three calls that confirm a rotation.

A restart sets each [declared upstream](/cloud/concepts/glossary/#declared-upstream)'s `sdk_settings` from the current declarations, with a new [egress key](/cloud/concepts/glossary/#egress-key) for each `key` setting that a provider's software development kit (SDK) reads ([An unchanged SDK](/cloud/guides/call-an-external-api-with-an-api-key/#an-unchanged-sdk)).

### Halt and resume

On the signed-in site, open the application's page. With two environments, choose one with **Environment** below the heading. Beside its state, choose **Pause app** or **Resume app**, check the named application and environment, and confirm.

Both controls need a sign-in within the last eight hours. Past that window, follow **Sign in again** in the control's place, then retry.

Pausing blocks new requests and stops new scheduled runs. Running work may be interrupted. The environment keeps its deployed version, data, files, and settings. On resume, schedules start from that instant; runs due during the halt are not replayed.

Your AI tool asks you and waits for your yes before halting production, unless you already asked for the halt. With no prior approval and nobody to ask, it stops and reports. Halting development and resuming either environment need no question. A resume before a promote or rollback you agreed to needs no second ask.

`tzcloud_halt_environment` stops an environment; with `resume: true`, it starts it again. Both forms take the application identifier and the environment, and finish before the call returns. 

```json
{ "application": "<application id>", "environment": "development" }
```

The exception is an environment whose `grain` is `pod` in `tzcloud_list_applications`. The grain describes how its compute runs; a pod uses a cluster shared with other applications. The pod stops within about 11 seconds after the call returns. Each returns the environment's `halted` member and an `outcome` of `halted`, `resumed`, or `unchanged`.

A [halted environment](/cloud/concepts/glossary/#halted-environment) keeps its version, data, and credentials. Its hostname returns 503 `environment_halted` on every path. A development halt ends at the next `tzcloud_deploy` to it or at `tzcloud_halt_environment` with `resume: true`. A production halt ends only at `tzcloud_halt_environment` with `resume: true`. Until then a promote or rollback to production is refused 409 `target_environment_halted`, and so is a deploy on an application with one environment.

Which credential can halt or resume:

- A production halt needs your signed-in session or a token minted for the whole account. A token limited to one application is refused 403 `account_credential_required`.
- `tzcloud_halt_environment` on development, and its `resume: true` form on either environment, accept your signed-in session, a token minted for the whole account, or a token limited to one application.

`tzcloud_halt_environment` refuses an environment with no deployed version, 409 `environment_never_deployed`. It also refuses one with a deploy, promote, or platform redeploy in progress, 409 `deploy_in_flight`. One case differs: on an application with one environment, halting production while a deploy is still building is accepted. It ends that deploy, which `tzcloud_read_status` then shows as failed, and nothing reaches production. Once the build is done, the halt is refused `deploy_in_flight` until the deploy ends, so call it again then.

The platform also halts an unused development environment itself. [The halted state](/cloud/concepts/applications-and-environments/#the-halted-state) says what each halt stops and when the platform halts an environment.

### Rename the application

`tzcloud_rename_application` requires the application identifier and a new valid name that differs from the current one. [Create the application](/cloud/getting-started/deploy-an-application/#1-create-the-application) gives the rules for a name. The call asks for a browser approval. The approval's description lists the two hostnames that stop working. It also counts the passkeys and the invitation links that stop working with them.

When the approved rename runs, it retires both previous hostnames, and the [serving router](/cloud/concepts/glossary/#serving-router) starts serving both new ones within its refresh interval. Each new hostname combines the new name with a new key that the platform chooses at that moment. So read the exact new hostnames in the outcome with `read_approval_status`.

The rename has these effects:

- Both previous hostnames, production's and development's, stop working for good. A request to either is refused `unknown_application` and is never redirected to the new hostname. The platform never gives a retired hostname to any application again. Renaming the application back to its old name gives it new hostnames, not the old ones.
- The previous name is freed, so another application in the account can take it.
- Each passkey that an [end user](/cloud/concepts/glossary/#end-user) registered on a previous hostname becomes a [stranded passkey](/cloud/concepts/glossary/#stranded-passkey) and stops working. The person registers a new passkey on the new hostname. While a domain of your own is attached, the rename still retires the passkeys registered on the old managed hostname, and its approval counts them. Detaching the domain afterwards brings none of them back ([Attach your own domain](/cloud/guides/attach-your-own-domain/#what-changes-for-your-users)).
- An end user who is signed in signs in again on the new hostname, because the browser keeps the sign-in cookie for the previous hostname only.
- A sign-in code requested on a previous hostname cannot be confirmed after the rename. The person requests a new code on the new hostname.
- Each `https` redirect URI a native client declares on a previous hostname stops working, while one on a domain of your own keeps working. Update the redirect URIs using [the tool that owns the environment's client list](/cloud/guides/sign-in-from-a-native-app/#1-declare-the-client-on-each-environment-s-realm). Do this before raising a client's minimum version. Until then, a call that repeats the old URIs is refused `invalid_redirect_uri`, and a submission whose manifest still lists them is refused naming that error ([Sign in from a native app](/cloud/guides/sign-in-from-a-native-app/#1-declare-the-client-on-each-environment-s-realm)).
- An invitation link that holds a previous hostname stops working, though the invitation itself can still be redeemed. Send the link again with the new hostname in place of the previous one. Or revoke the invitation by calling `tzcloud_invite_end_user` with its identifier in `invitation`, leaving out `email` and `products`, and issue a new one.
- Each deployed environment restarts, so its running copy's `APP_PUBLIC_HOST` setting names the new hostname without a deploy.
- Where a restart is refused, the outcome's `container` member names the refusal. That running copy keeps the previous hostname in `APP_PUBLIC_HOST` until `tzcloud_restart_application`, or the next deploy or promote of its environment, writes the new one.
- The application keeps its identifier, size, manifest, deployed code, secrets, tokens, and usage.

[Renaming an application](/cloud/concepts/applications-and-environments/#renaming-an-application) explains the name rules and what happens when another change reaches the application before the rename runs.

### Turn the development environment on

[Test in development, then promote](/cloud/guides/turn-on-development-and-promote/) turns development on, deploys a version there, and promotes it to production.

### Delete the development environment

`tzcloud_delete_environment` turns development off again, after a person approves the deletion in the browser. It removes the development environment, and the application has one environment again, so the next deploy goes to production. A call that names `production` is refused 400 `invalid_request`, because production is deleted only with its application, through `tzcloud_delete_application`.

On an application with one environment, the call removes the development database and the other records your [local runs](/cloud/concepts/glossary/#local-run) keep. It does so where a database setup exists, finished or stopped partway, where an earlier deletion of them stopped, or where development records remain. Production is untouched. Otherwise it is refused 409 `environment_not_created`.

The deletion ends development's schedules, and a later `tzcloud_create_environment` declares them again from the manifest. The next `tzcloud_submit_manifest` sets up development's records for local runs again, including its database and storage parts. It also creates development's credentials again, but creates no development realm. [Deleting the development environment](/cloud/concepts/applications-and-environments/#deleting-the-development-environment) lists what the deletion removes and what stays.

If you turn development on again with `tzcloud_create_environment`, call `tzcloud_submit_manifest` before the first deploy to development, so that development has its records again, its database among them. Its new realm takes the manifest's `realm` member where there is one, and otherwise the default sign-in methods, which [Manage end users](/cloud/guides/manage-end-users/) configures.

### Delete the application

`tzcloud_delete_application` removes the application with every environment it has, after a person approves it in the browser:

1. Your AI tool calls it with the application identifier and prints the approval link in the response.
2. You open the link and approve on the browser page, which shows the platform's description of what the deletion removes. It lists each kind and counts the storage areas, secrets, upstreams, and outstanding transfer grants. The page also links to this section for what the deletion keeps. Above its buttons, it says the deletion cannot be undone and that Turn Zero offers no way to restore what it deletes.
3. Your AI tool reads the outcome with `read_approval_status`.

You can also start the deletion from the application's page on the signed-in site. **Delete app**, below the page's sections, names the application, asks you to confirm, and opens the same approval page. While the deletion runs, the application's page turns **Delete app** off and says the deletion is under way. **Pause app** and **Resume app** are absent. Once it finishes, the page shows no such application.

The deletion removes, one kind at a time:

- each environment's compute, the image repository, and the published assets;
- every end-user [realm](/cloud/concepts/glossary/#realm) with every user, identity, session, passkey, and invitation in them;
- the push configurations, the queued deliveries, and the month's counts;
- both databases with their roles and credentials;
- its [issue-tracking space](/cloud/concepts/glossary/#issue-tracking-space), or both spaces of an application with one for each environment, each deleted at the issue service with every record in it;
- the daily copies of its own space (a copy being written at that moment is deleted at the next daily run);
- its binding to an issue space of your account's own, which keeps its records;
- the secrets stored at the application's scopes, both platform credentials, the tokens minted for the application, and the [transfer grants](/cloud/concepts/glossary/#transfer-grant);
- the schedule rows, the upstream declarations bound to the application, and the [storage areas](/cloud/concepts/glossary/#storage-area) bound to it with their files;
- the log entries and counter totals;
- last, the application row with its version history, its label retired and never reused.

Secrets stored for the whole account stay. So does any storage area or upstream that was declared before an application binding was required and is not yet bound to one. The usage meters keep their rows. The secret store keeps deleted secret values for ninety days before it purges them, and no action of yours can read or restore them ([Secrets](/cloud/backend-packages/secrets/)). The deletion does not revoke a key at the service that issued it, so replace the key there if it should stop working.

Console output from container hosting stays in the hosting provider's log store for up to thirty days; deletion and `tzcloud_purge_logs` do not remove it. Saved console excerpts from ended pods are part of the environment's log stream and are deleted with it. An approved deletion cannot be undone.

A deletion that stops because one kind fails to be removed ends `execution_failed`, and the Refusals table below gives its remedy. [The pending action](/cloud/concepts/what-happens-without-asking/#the-pending-action) explains the pending action and its outcomes.

## Expected result

- After a rollback, `tzcloud_read_status` shows production's `deploy.state` as `deployed` and its `version` as the number you named. `tzcloud_list_versions` shows a new `"promote"` row for production with `serving: true`.
- After a halt, the environment's `halted` member contains `at` and `by`, and its hostname returns 503 `environment_halted`. After a resume, `halted` is `false`.
- After an approved rename, `read_approval_status` shows the record `completed`, and its outcome gives the new hostname.
- After an approved deletion, `read_approval_status` shows the record `completed`, and its outcome lists what was removed. After the development environment's deletion, `tzcloud_read_status` lists production alone.

## Refusals

See the [refusals reference](/cloud/reference/refusals/) for other platform errors.

The refusals page holds the approval page's own refusals too. A refusal changes nothing on the platform. The status is the one the HTTP route returns, and the MCP tool returns the same refusal name. One row, `execution_failed`, is an outcome a pending action records, which `read_approval_status` shows, and not a response to the call. Two more, `cell_not_configured` and `cell_unavailable`, refuse a deletion after its approval, so `read_approval_status` shows them too, on a record that ended `failed`.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `version_already_serving` | 409 | `tzcloud_roll_back` named production's serving version. | Name an earlier version. To mint a new production platform credential, call `tzcloud_promote` instead, or deploy again on an application with one environment. |
| `version_newer_than_serving` | 409 | `tzcloud_roll_back` named a version newer than production's serving one. | Call `tzcloud_promote` on an application with two environments to apply its checks; on one, deploy that code again. |
| `no_such_version` | 404 | `tzcloud_roll_back`: the version is not a deployed row of the application, or its environment was deleted. | Name a row `tzcloud_list_versions` returns with `state: "deployed"`. |
| `version_image_pruned` | 409 | `tzcloud_roll_back`: the platform has deleted the named version's image. | Choose a version `tzcloud_list_versions` marks `promotable`, or deploy that version's artifact again as a new version, and promote it where the application has two environments. |
| `target_environment_halted` | 409 | `tzcloud_roll_back` while production is halted, or `tzcloud_restart_application` on a halted environment. | Call `tzcloud_halt_environment` with `resume: true`, then call again. |
| `deploy_in_flight` | 409 | `tzcloud_roll_back` while a production promote is in progress, or `tzcloud_halt_environment` or `tzcloud_restart_application` while a deploy, promote, or redeploy of the environment is. | Wait with `tzcloud_read_status` and `wait_seconds`, up to 45, until `deploy.state` is no longer `deploying`, then call again. |
| `environment_never_deployed` | 409 | `tzcloud_halt_environment` or `tzcloud_restart_application`: the environment has no deployed version, so there is nothing to halt or restart. | Deploy first. |
| `account_credential_required` | 403 | `tzcloud_halt_environment` on production under a token limited to one application. | Call it under your signed-in session or a token minted for the whole account. |
| `name_taken` | 409 | `tzcloud_rename_application`: the account already has a live application with that name. | Choose another name. |
| `cell_not_configured` | 503 | `tzcloud_delete_environment`, after the approval: the platform has no record of where the development environment is hosted, and no hosting cell is registered or open to record one. Nothing was deleted. | Nothing on your side corrects this. Report the refusal with its `detail`, and request the deletion again once platform staff have opened a hosting cell. |
| `cell_unavailable` | 503 | `tzcloud_delete_environment`, after the approval: the platform has no record of where the development environment is hosted, and every open hosting cell is full. Nothing was deleted. | Nothing on your side corrects this. Report the refusal with its `detail`, and request the deletion again once platform staff have added room for it. |
| `deletion_in_progress` | 409 | A deletion of the application or one of its environments is running. Reads, `read_approval_status`, and a repeat of the same deletion are accepted. A deletion approved while another deletion of the same application holds it ends failed with this refusal. That refusal's detail gives the instant the other deletion's hold lapses; if its process stopped, request your deletion again after that instant. An account deletion waits for a running deletion of one of its applications, about six minutes at most. | Wait for the deletion to finish; `read_approval_status` shows whether it completed. If it failed, request the same deletion again to complete it. |
| `destructive_class_required` | 403 | `tzcloud_delete_application`, `tzcloud_delete_environment`, or `tzcloud_rename_application` ran under a credential without the `destructive` grant. No pending action is created. | Call it from the connected session, or under a token minted with the `destructive` grant. |
| `execution_failed` | none | The pending action failed without a named refusal. A deletion's outcome includes `receipts` for what it removed before the failure. | Read the receipts and the current state, then request the deletion again. A kind already removed reports zero removals. |

## Related

- [Deploy from your computer](/cloud/getting-started/deploy-an-application/) creates the application and deploys it to production, and [Test in development, then promote](/cloud/guides/turn-on-development-and-promote/) covers the promote of an application with two environments.
- [Applications and environments](/cloud/concepts/applications-and-environments/) explains the version history, the halted state, renaming, and the two deletions.
- [What happens without asking](/cloud/concepts/what-happens-without-asking/) explains the browser approval and the pending action.
- [tzcloud_roll_back](/cloud/reference/actions/roll-back/), [tzcloud_list_versions](/cloud/reference/actions/list-versions/), [tzcloud_halt_environment](/cloud/reference/actions/halt-environment/), [tzcloud_restart_application](/cloud/reference/actions/restart-application/), [tzcloud_rename_application](/cloud/reference/actions/rename-application/), [tzcloud_delete_environment](/cloud/reference/actions/delete-environment/), and [tzcloud_delete_application](/cloud/reference/actions/delete-application/) are the actions' generated reference entries.
