This error occurs when Terraform tries to select or use a workspace that doesn't exist in your current backend. You can fix it by creating the workspace first or using the auto-create flag in newer Terraform versions.
Terraform workspaces allow you to manage multiple environments (dev, staging, production) from the same configuration using separate state files. When you run `terraform workspace select` for a workspace that hasn't been created yet, Terraform cannot find the corresponding state data and returns the "workspace not found" error. The error prevents Terraform from initializing because it cannot load the state file for the workspace you're trying to use. This is a safety mechanism to prevent accidental state loss or misconfiguration.
First, check which workspaces are actually available in your current backend and configuration:
terraform workspace listThis shows all existing workspaces (marked with an asterisk for the current one) and confirms whether your target workspace exists.
If the workspace isn't listed, create it before trying to select it:
terraform workspace new workspace-nameReplace "workspace-name" with your actual workspace name. This command creates a new workspace and automatically switches to it, along with creating the necessary state file in your backend.
After creation, you can switch between workspaces using:
terraform workspace select workspace-nameVerify you're on the correct workspace:
terraform workspace showFor Terraform version 1.4 and later, you can use the -or-create flag to automatically create a workspace if it doesn't exist:
terraform workspace select -or-create workspace-nameThis is useful in CI/CD pipelines where you want to ensure the workspace exists without separate creation steps.
If using a remote backend (S3, Terraform Cloud, Azure Storage, etc.), ensure:
1. The backend configuration is correct (same bucket/container/organization)
2. You have proper credentials configured
3. The workspace naming matches what's in the backend
For S3 backend, verify your terraform block includes the correct bucket and key prefix:
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
workspace_key_prefix = "workspaces" # Enables workspace support
}
}For Terraform Cloud, ensure you're authenticated and connected to the correct organization.
When using remote backends like S3, Azure Storage, or Terraform Cloud, workspace state is stored differently than with local state. Local workspaces create a terraform.tfstate.d/<workspace-name> directory, while remote backends store workspace state on the server. Ensure your backend configuration includes workspace support before using workspaces.
For Terraform Cloud, workspaces are created at the organization level and may require different authentication or permissions. Team members may not have access to create workspaces in the organization.
In CI/CD pipelines, consider using the -or-create flag (Terraform 1.4+) or adding explicit workspace creation steps to prevent failures when deploying to new environments. This is safer than manually creating workspaces out of band.
Error: Error rendering template: template not found
How to fix "template not found" error in Terraform
Error: Error generating private key
How to fix 'Error generating private key' in Terraform
Error creating Kubernetes Service: field is immutable
How to fix "field is immutable" errors in Terraform
Error: Error creating local file: open: permission denied
How to fix "Error creating local file: permission denied" in Terraform
Error: line endings have changed from CRLF to LF
Line endings have changed from CRLF to LF in Terraform