# Roll back to an earlier deployment

> Run an earlier deployment's image again when a new version misbehaves, without waiting for a build.

Source: https://docs.coritan.com/apps/roll-back-a-deployment/

In the dashboard:

- /dashboard/apps/…/deployments: https://www.coritan.com/dashboard/apps

Roll back when a new version misbehaves and you want the one before it back. A rollback is a new deployment of an earlier deployment's image, so it skips the build and goes live as soon as its replicas are healthy.

## Before you begin

- The app must be `active`.
- The deployment you roll back to must have gone live at some point, and must not be the one serving the app now. In the dashboard, only such a deployment offers **Roll back to this…**. Through the API, its `can_rollback` field says whether it qualifies.
- For an organization's app, you need the owner or admin role in the organization.

## Roll back in the dashboard

1. Open the app from **Apps** in the [dashboard](https://www.coritan.com/dashboard/apps) and select the **Deployments** tab.
2. Open the menu at the end of the deployment you want back and select **Roll back to this…**. On the deployment's own page, **Roll back to this…** is in its header.
3. The dialog names the deployment by its short commit, such as `Roll back to 3e7d2c1?`. Select **Roll back**.

A message confirms `Rollback started.`, and the new deployment's page opens. The deployment serving now keeps serving until the new one is ready.

## What a rollback runs

A rollback runs the earlier deployment's image, so the code and every value the build read are as they were when that image was built. The variables the running app reads, the regions and the number of replicas in each come from the app as it is now.

Replicas of the earlier deployment that we have not removed yet start again instead of new ones, which makes the rollback quicker. We remove a replica 30 minutes after it stops taking requests ([Going live](/apps/how-apps-work/#going-live)).

The push webhook keeps working after a rollback, so the next push to the app's branch deploys that push. To keep the old version running, stop pushing to the branch, or fix the problem and push the fix.

## Result

A new deployment appears first in the app's history, with the earlier deployment's commit and `Rollback` as its source. Through the API, its `source` and `trigger` are both `rollback`. It goes live once its replicas are healthy, like any other deployment, and the one it replaces becomes **Superseded**. If the rollback fails, the deployment that served the app keeps serving.

## Troubleshooting

`Only a deployment that was ready once can be rolled back to`
: The deployment never went live, so it has no image that ran. Choose one that offers **Roll back to this…**, or whose `can_rollback` is `true`.

`That deployment is already serving`
: It is the current deployment. There is nothing to roll back.

`The app is suspended; it cannot deploy`
: We suspended the app. [Contact support](/support/conversations/) to find out why.

`These regions cannot run apps: syd`
: A region the app names cannot run apps now. Change the app's regions ([Change the settings](/apps/app-settings/#change-the-settings)), then roll back again.

`No region can run apps right now`
: The app runs in every region, and no region can take replicas at the moment. Try again later.

## Related

- [Deploy an app](/apps/deploy-an-app/)
- [Read a deployment and its build log](/apps/read-a-deployment/)
- [How Apps works](/apps/how-apps-work/#redeploys-and-rollbacks)

## With the API

[`POST /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`](/api/reference/client/apps/#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-rollback) rolls the app back to the deployment in the path. For an organization's app, send it to [`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`](/api/reference/organizations/organization-apps/#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-rollback).

```bash
curl -X POST https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21/deployments/8c4e1a7d-2f9b-4d6e-b3a8-6e1f9c2d5a10/rollback \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

It answers `201` with the new deployment:

```json
{
  "deployment": {
    "uuid": "6a2f9d1c-4e8b-4b7a-a5c3-9d0e1f2a3b4c",
    "status": "deploying",
    "source": "rollback",
    "trigger": "rollback",
    "git_ref": "main",
    "git_sha": "3e7d2c1b0a9f8e7d6c5b4a3928170f6e5d4c3b2a",
    "image_ref": "registry.example.net/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21:8c4e1a7d-2f9b-4d6e-b3a8-6e1f9c2d5a10",
    "regions": ["fra", "iad"],
    "is_current": false,
    "in_flight": true
  }
}
```

The example shortens the deployment ([App and deployment fields](/apps/fields/#deployment)).

| Status | `detail` | Cause |
| --- | --- | --- |
| `404` | `Deployment not found` | The deployment belongs to another app, or does not exist. |
| `409` | `{"error": "not_rollbackable", "message": "Only a deployment that was ready once can be rolled back to"}` | The deployment never went live. |
| `409` | `{"error": "already_current", "message": "That deployment is already serving"}` | It is the current deployment. |
| `409` | `{"error": "app_not_active", "message": "The app is suspended; it cannot deploy"}` | The app is suspended. |
| `409` | `No region can run apps right now` | The app runs in every region, and none can take replicas. |
| `422` | `{"message": "These regions cannot run apps: syd", "unavailable": ["syd"], "available": ["fra", "iad"]}` | A region the app names cannot run apps now. |
| `429` | `{"error": "rate_limited", "message": "Too many deployments of this app. Wait a few minutes.", "retry_after_seconds": 600}` | The app started 30 deployments in the last 10 minutes. |

## API

- `POST /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`: Rollback app (https://docs.coritan.com/api/reference/client/apps/#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-rollback)
- `POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`: Rollback app (https://docs.coritan.com/api/reference/organizations/organization-apps/#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-rollback)