TerraformPilot

DevOps

Fix Terraform Error: Workspace Does Not Exist

Fix terraform workspace does not exist errors. Create missing workspaces, auto-create in CI/CD, handle backend workspace config, and migrate between workspaces.

LLuca Berton1 min read

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

#
  1. Workspace never created — first deploy to this environment
  2. Backend changed — migrated from local to S3, workspaces didn't carry over
  3. CI/CD fresh runner — .terraform/ is empty, workspace selection saved there
  4. Different backend — dev and prod use different state backends
  5. 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

#

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.

#Terraform#Troubleshooting#DevOps#Error Fix#Infrastructure as Code

Share this article

Related articles