Quick Answer
# Create the workspace
terraform workspace new production
# Or auto-create if it doesn't exist
terraform workspace select production 2>/dev/null || terraform workspace new production
The Error
Error: Currently selected workspace "production" does not exist.
Available workspaces:
default
dev
staging
Or after changing backends:
Error: Workspace "production" doesn't exist.
You can create this workspace with the "new" subcommand
or include the "-or-create" flag with the "select" subcommand.
What Causes This
- Workspace never created — first deploy to this environment
- Backend changed — migrated from local to S3, workspaces didn’t carry over
- CI/CD fresh runner —
.terraform/is empty, workspace selection saved there - Different backend — dev and prod use different state backends
- Terraform Cloud — workspace naming doesn’t match local names
Solution 1: Create the Workspace
terraform workspace list # See what exists
terraform workspace new production
terraform workspace select production
Solution 2: Auto-Create in CI/CD
# Idempotent — works whether workspace exists or not
terraform workspace select $ENVIRONMENT 2>/dev/null || terraform workspace new $ENVIRONMENT
Or with Terraform 1.8+:
terraform workspace select -or-create $ENVIRONMENT
Full CI/CD script:
# GitLab CI
.deploy:
script:
- terraform init
- terraform workspace select -or-create ${CI_ENVIRONMENT_NAME}
- terraform plan -out=plan.tfplan
- terraform apply plan.tfplan
deploy-dev:
extends: .deploy
environment:
name: dev
deploy-prod:
extends: .deploy
environment:
name: production
Solution 3: After Backend Migration
When changing from local to remote backend, workspaces don’t automatically migrate:
# Migrate state to new backend
terraform init -migrate-state
# Then create workspaces in the new backend
terraform workspace new dev
terraform workspace new staging
terraform workspace new production
Solution 4: Terraform Cloud Workspace Names
Terraform Cloud workspace names may differ from local:
terraform {
cloud {
organization = "myorg"
workspaces {
# Option 1: exact name
name = "myapp-production"
# Option 2: tag-based (select at init)
tags = ["myapp"]
}
}
}
With tags, select at init:
terraform init
# Terraform prompts: Which workspace? → select "myapp-production"
Workspace Best Practices
List and Switch
terraform workspace list # Show all workspaces (* = current)
terraform workspace show # Show current workspace name
terraform workspace select dev # Switch to dev
Use terraform.workspace in Config
locals {
config = {
dev = { instance_type = "t3.micro", count = 1 }
staging = { instance_type = "t3.small", count = 2 }
production = { instance_type = "t3.large", count = 3 }
}
env = local.config[terraform.workspace]
}
resource "aws_instance" "app" {
count = local.env.count
instance_type = local.env.instance_type
tags = {
Environment = terraform.workspace
}
}
The “default” Workspace
- Always exists, cannot be deleted
- If you use workspaces, avoid deploying to
default - Add a check:
locals {
valid_workspaces = ["dev", "staging", "production"]
}
resource "null_resource" "workspace_check" {
count = contains(local.valid_workspaces, terraform.workspace) ? 0 : 1
provisioner "local-exec" {
command = "echo 'ERROR: Invalid workspace ${terraform.workspace}' && exit 1"
}
}
Hands-On Courses
- Terraform for Beginners on CopyPasteLearn
- Terraform By Example — practical code examples
Conclusion
Create the workspace with terraform workspace new NAME or use terraform workspace select -or-create NAME in CI/CD. After backend migrations, workspaces need to be recreated in the new backend. In Terraform Cloud, ensure workspace names match your configuration.