Troubleshooting

If something is not working, find the symptom below. Most issues come down to source reachability, workspace scope, or override rule shape.

Remote registration fails verification

Symptom: dst snap remote postgres … returns a validation error like “connector connectivity verification failed — check your connection details and ensure the source is reachable.”

Snap verifies it can reach a source before saving the remote. This error means the source could not be reached with the credentials you supplied.

Confirm the DSN’s host, port, user, password, and database are correct, and that the database accepts connections from outside its network.
If the source is only reachable through a bastion, register with --tunnel-mode ssh and the --tunnel-bastion-host / --tunnel-bastion-user / --tunnel-remote-host / --tunnel-remote-port flags. The SSH key must be supplied as a pre-uploaded --tunnel-key-secret-ref.
For S3 remotes, check the bucket name, region, and credentials, and add --path-style for MinIO-style endpoints.

“no active workspace set”

Symptom: a command exits with “no active workspace set — run dst workspace switch <name> first.”

Every Snap command acts inside a workspace. Set one before running remote, branch, or fixture commands:

dst workspace switch my-team

See Workspaces for how workspaces scope your data.

Branch creation is rejected

Symptom: dst snap create (or POST /v1/snaps) returns a 4xx instead of provisioning.

The most common causes map to specific responses:

403 “workspace does not have access to this connector — add it as a remote first.” The branch’s workspace has no share for that connector. Register the source as a remote in this workspace, or pass the --connector-id of a remote that is already shared here.
409 “connector is not healthy.” The remote is still pending verification or in error. Run dst snap remote show <id> and wait for healthy, or re-register if it stayed in error.
409 “connector sync lag exceeds requested max_lag.” You passed --max-lag and the source has fallen further behind than allowed. Raise --max-lag, drop it, or branch from a fresher checkpoint with --at-checkpoint.
409 parent snap is not ready. When forking with --from-snap, the parent branch must be in ready state first.
429 OPERATIONAL_CAPACITY. Too many of the workspace’s branches are provisioning at the same time (five by default). This one clears on its own — wait for the in-flight branches to reach ready and create again.
429 quota_exceeded. The workspace has used up the branch allowance its plan enforces. The response says how many branches you have used and what the limit is. Delete branches you no longer need with dst snap delete <id>, or move to a plan with a larger allowance. Only branches you created count — deleted ones are released, and branches another product forked on your behalf (a Preview, say) are counted separately.
403 workspace_suspended / entitlement_required. The workspace can’t create branches at all — check its plan and standing in account settings.
503 quota_policy_unavailable. Snap could not read your plan’s allowance, so it refused rather than guessing. Retry shortly.

Branch provisioning times out

Symptom: dst snap create prints Provisioning… then fails with a timeout, or dst snap status <id> stays in provisioning.

A branch goes pending → provisioning → ready; the CLI polls for up to five minutes. If it never reaches ready:

Check the branch state with dst snap status <id>. A state of error means provisioning failed — delete it and try again.
Confirm the source is still reachable; a source that went down mid-provision will stall hydration.
Poll the operation with GET /v1/operations/{id} (its ID is returned by the create call) to watch the branch advance toward ready.

Override rule is rejected or the branch errors

Symptom: a validation error on create, or the branch lands in error because of an override.

Validation error on create. Each rule needs a non-empty table and at least one set column with a non-empty expression. set values are raw SQL, so quote string literals ('me@example.com'), and use false / NULL rather than bare words you intend as literals.
Branch errors during hydration. An override referencing a column that does not exist fails materialization loudly, and the branch stays in error until the rule is fixed. Recheck the column names against the source schema and recreate the branch — rules are immutable, so you cannot edit them in place.

A branch will not delete

Symptom: dst snap delete <id> returns a 409 conflict mentioning fixtures.

A branch that is pinned by one or more fixtures cannot be deleted — the fixture is the durable handle and would dangle. Delete the referencing fixtures first:

dst snap fixture list
dst snap fixture delete <fixture-name>
dst snap delete <id>

SQL trace is empty

Symptom: dst snap trace <snap-id> returns a single informational row and no events, or reports that psql was not found.

SQL tracing is opt-in. The branch’s proxy must have been started with SNAP_TRACE_SQL=1; without it the trace ring stays empty.
dst snap trace shells out to psql. If psql is not on your PATH, the command prints the equivalent psql … -c 'SNAP TRACE' line for you to run yourself, or use --print to always just print it.

Migrations and ORM reflection misbehave

Symptom: Alembic revision --autogenerate produces false diffs, or reflection-heavy tooling reports missing objects against a branch.

Use a branch as the target for already-authored migration upgrade / downgrade runs and application testing — not as the authoritative database for --autogenerate. Snap reconstructs base tables, enums, unique indexes, and foreign keys, but not the full catalog, so:

Schemas other than public are branched — Snap discovers every user schema in the source and gives each its own holding area. But Snap resolves an unqualified table name as public, so a search_path that points somewhere else won’t redirect it. Schema-qualify the table (billing.invoices) in the SQL your tooling emits. See Schemas.
For SQLAlchemy apps using postgresql+asyncpg://, a synchronous engine such as postgresql+psycopg:// is often the better choice for the migration run. If you do run Alembic with asyncpg, create a dedicated engine for the run and dispose it afterward.
Prefer sslmode=prefer over forcing disable on generated DSNs — the negotiation-first path is the most portable.
If you need authoritative autogenerate output, point Alembic at the real source database and use the branch only to execute the resulting migrations.

Other limits to know

A branch’s snapshots and mutations live for the life of the branch; deleting it releases everything.
RETURNING clauses on INSERT / UPDATE / DELETE pass through but are not merged into the audit log.
Sequences are reset to the source’s max values at materialization time; rows inserted into the source after you branch are not reflected.
Views, functions, triggers, and other non-table objects have partial support — expect gaps for tooling that depends heavily on them.

Next steps

ReferenceExact commands, endpoints, and env vars.

ConceptsThe mental model behind branches and override rules.