> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Errors and rollbacks

How Blueprints catches mistakes early and what happens when a deploy fails.

## Most errors happen before deploy

Validation runs at more than one point, so problems surface as early as possible:

- **As you write.** The [definers](https://www.sanity.io/docs/blueprints/blueprint-config) check their input when you call them, so a missing required field or a malformed value is flagged in your editor and at build time.
- **Before applying.** When you run `plan` or `deploy`, the whole file is validated (structurally and per resource) before any change is made.

Because `plan` is read-only, running it is the safe way to surface most errors without touching anything.

## Kinds of failure

##### Kinds of failure

| Failure | What it means |
| --- | --- |
| Validation error | A resource is missing a required field, has an invalid value, or the file is structurally wrong. Caught before deploy. |
| Unresolved reference or cycle | A $.resources.<name> points at something that doesn't exist, or two resources depend on each other. See The resource graph. |
| Scope mismatch | An organization-scoped resource type on a project-scoped stack, or a project-scoped resource with no resolvable project. See Stacks and scope. |
| Deletion-policy violation | A change would remove a resource whose deletion policy forbids it (for example a retain or protect resource). |
| Execution failure | A change passed validation but failed while being applied; for instance, an underlying service rejected it. |

Errors come back with a clear name, a human-readable message, and the path to the resource involved, so you can map the failure straight to a line in your file.

## What rollback does

If a deploy fails after some changes have already been applied, Blueprints attempts to undo the completed changes in reverse order and marks the operation as failed. The goal is to leave the stack consistent rather than half-applied.

> [!WARNING]
> Rollback is best-effort
> Rollback unwinds the actions it can, in reverse. It isn't a guaranteed atomic restore of the entire stack: some actions may not be reversible, and references to resources owned by other stacks are never touched. After a failed deploy, run `blueprints info` to see the current state, fix the cause, and deploy again.

## Reading what happened

A deploy streams its progress until the operation finishes. To review a past deploy after it has stopped tailing, including the messages from a failure, use the logs:

**npm**

```shell
# Inspect current state
npx sanity@latest blueprints info

# Re-read logs from earlier operations
npx sanity@latest blueprints logs
```

**pnpm**

```shell
# Inspect current state
pnpm dlx sanity@latest blueprints info

# Re-read logs from earlier operations
pnpm dlx sanity@latest blueprints logs
```

**yarn**

```shell
# Inspect current state
yarn dlx sanity@latest blueprints info

# Re-read logs from earlier operations
yarn dlx sanity@latest blueprints logs
```

**bun**

```shell
# Inspect current state
bunx sanity@latest blueprints info

# Re-read logs from earlier operations
bunx sanity@latest blueprints logs
```

## Recovering

1. Read the error message and the resource path it points to.
2. Fix the blueprint file (or the underlying resource, if something external changed).
3. Run `blueprints plan` to confirm the diff is now what you expect.
4. Run `blueprints deploy` again.

#### Related

[The resource graph](https://www.sanity.io/docs/blueprints/resource-graph)
How resources reference each other with the $ syntax, and why a blueprint file is a connected system.

[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.

[Blueprints CLI command reference](https://www.sanity.io/docs/cli-reference/cli-blueprints)
Reference documentation for the Sanity CLI Blueprints command.