Terraform "workspace ... does not exist" in CI

By Daniel Zoghalchali·Latchkey

Terraform tried to select a state workspace that the backend does not have. terraform workspace select only switches to existing workspaces, so a CI job that selects before the workspace is created fails.

What this error means

A terraform workspace select X step fails with "workspace \"X\" does not exist" and a hint to create it with terraform workspace new.

Error: Workspace "staging" doesn't exist.

You can create this workspace with the "new" subcommand or include the "-or-create"
flag with the "select" subcommand.

Common causes

Selecting a workspace before it is created

The pipeline calls workspace select staging, but no staging workspace exists in the backend yet.

A per-environment workspace missing in a fresh backend

A new backend has only default, so a first run for another environment finds no matching workspace.

How to fix it

Select or create in one step

1. Use terraform workspace select -or-create=true <name> so it is created if absent.
2. Or create it explicitly with terraform workspace new <name> on first use.
3. Re-run so the workspace exists before plan/apply.

terraform workspace select -or-create=true staging

Create the workspace idempotently

Guard the create so re-runs do not fail when the workspace already exists.

terraform workspace new staging || terraform workspace select staging

How to prevent it

• Use select -or-create=true for per-environment workspaces in CI.
• Create workspaces on first use, not lazily at select time.
• Do not assume a fresh backend has anything but default.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation