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 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
planordeploy, 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
| 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.
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:
# Inspect current state npx sanity@latest blueprints info # Re-read logs from earlier operations npx sanity@latest blueprints logs
# Inspect current state pnpm dlx sanity@latest blueprints info # Re-read logs from earlier operations pnpm dlx sanity@latest blueprints logs
# Inspect current state yarn dlx sanity@latest blueprints info # Re-read logs from earlier operations yarn dlx sanity@latest blueprints logs
# Inspect current state bunx sanity@latest blueprints info # Re-read logs from earlier operations bunx sanity@latest blueprints logs
Recovering
- Read the error message and the resource path it points to.
- Fix the blueprint file (or the underlying resource, if something external changed).
- Run
blueprints planto confirm the diff is now what you expect. - Run
blueprints deployagain.
The resource graph
How resources reference each other with the $ syntax, and why a blueprint file is a connected system.
Stacks and scope
How one blueprint file maps to many stacks, and what project versus organization scope means.
Blueprints CLI command reference
Reference documentation for the Sanity CLI Blueprints command.