terraform workspace: new, select, list & CI Errors
Multiple named states from one configuration - one per environment.
terraform workspace manages named workspaces, each with its own state, backed by the same configuration and backend. They are handy for ephemeral or per-branch environments.
What it does
Workspaces let a single configuration hold separate states (default, staging, prod). workspace new creates one, workspace select switches to it, and workspace list shows them with the active one marked. terraform.workspace exposes the current name to your config.
Common usage
# List workspaces (current is marked with *)
terraform workspace list
# Create and switch to a new workspace
terraform workspace new staging
# Switch to an existing workspace (create if missing, 1.4+)
terraform workspace select -or-create prod
# Show the active workspace
terraform workspace showCommon error in CI: workspace does not exist
select fails with "Error: Workspace \"prod\" does not exist" when a pipeline assumes a workspace that was never created. Fix: use terraform workspace select -or-create <name> (Terraform 1.4+) so the job creates the workspace on first run, or guard with terraform workspace new <name> || terraform workspace select <name>. Confirm the backend supports workspaces - local and S3 do; some do not.
Key subcommands
| Subcommand | Purpose |
|---|---|
| new NAME | Create and switch to a workspace |
| select NAME | Switch to an existing workspace |
| select -or-create NAME | Switch, creating if absent (1.4+) |
| list | List all workspaces |
| show | Print the current workspace |
| delete NAME | Delete an empty workspace |