Fix Terraform Error - Terraform Cloud Workspace Not Found

Quick Answer

The Terraform Cloud workspace doesn't exist in the specified organization. Create it in the TFC UI, verify the organization and workspace names for typos, and ensure your API token has access.

The Error

Error: No workspace named "production" found in organization "my-org"

Error: Failed to read organization "my-org":
  resource not found

Error: No workspaces found matching prefix "app-"

What Causes This Error

1. Workspace Doesn't Exist

The workspace needs to be created before terraform init — Terraform doesn't auto-create workspaces in TFC.

2. Organization Name Typo

The organization in your backend config doesn't match the actual TFC organization name.

3. Wrong Workspace Name

The workspace name in config doesn't match the name in TFC (case-sensitive).

4. API Token Permissions

Your TFC token doesn't have access to the organization or workspace.

5. Prefix Mismatch

Using workspaces { prefix = "app-" } but no workspace starts with app-.

How to Fix It

Solution 1: Create the Workspace in TFC

# Using TFC API
curl -s \
  --header "Authorization: Bearer $TFC_TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data '{
    "data": {
      "type": "workspaces",
      "attributes": {
        "name": "production",
        "execution-mode": "local"
      }
    }
  }' \
  "https://app.terraform.io/api/v2/organizations/my-org/workspaces"
 
# Or use the TFC UI:
# Settings → Workspaces → New Workspace → CLI-Driven Workflow

Solution 2: Verify Organization and Workspace Names

# Check these match exactly (case-sensitive)
terraform {
  cloud {
    organization = "my-org"  # Must match TFC org name exactly
 
    workspaces {
      name = "production"     # Must match TFC workspace name exactly
    }
  }
}

# List your organizations
curl -s \
  --header "Authorization: Bearer $TFC_TOKEN" \
  "https://app.terraform.io/api/v2/organizations" | jq '.data[].attributes.name'
 
# List workspaces in an org
curl -s \
  --header "Authorization: Bearer $TFC_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/my-org/workspaces" | jq '.data[].attributes.name'

Solution 3: Fix API Token

# Login to Terraform Cloud (generates/validates token)
terraform login
 
# Or set the token manually
export TF_TOKEN_app_terraform_io="your-token-here"
 
# Verify the token works
curl -s \
  --header "Authorization: Bearer $TFC_TOKEN" \
  "https://app.terraform.io/api/v2/account/details" | jq '.data.attributes.username'

Solution 4: Use Tags Instead of Prefix (TFC 1.1+)

terraform {
  cloud {
    organization = "my-org"
 
    workspaces {
      tags = ["app", "production"]  # Match by tags instead of name/prefix
    }
  }
}

Solution 5: Use the Older Backend Config

# Legacy backend config (still works)
terraform {
  backend "remote" {
    organization = "my-org"
 
    workspaces {
      name = "production"
      # OR
      # prefix = "app-"  # Matches app-dev, app-staging, app-prod
    }
  }
}

Troubleshooting Checklist

1. ✅ Does the workspace exist in TFC? (Check the UI or API)
2. ✅ Is the organization name correct? (Case-sensitive)
3. ✅ Is the workspace name correct? (Case-sensitive)
4. ✅ Does your API token have access? (terraform login)
5. ✅ If using prefix, do any workspaces match the prefix?
6. ✅ Are you connected to the right TFC host? (TFC vs TFE)

Prevention Tips

• Create workspaces before init — automate workspace creation in CI setup scripts
• Use terraform login to validate tokens before running init
• Store workspace config in variables — easier to catch typos in one place
• Use tags for workspace selection — more flexible than prefix matching
• Document your TFC organization structure in the project README

Related Articles

• All Troubleshooting Articles
• Terraform Troubleshooting - Common Errors and Solutions
• Terraform Glossary

Conclusion

Workspace not found errors mean the workspace doesn't exist in the specified TFC organization. Create it first (UI or API), verify the org and workspace names are exact matches, and ensure your API token has proper access. Use terraform login to validate your credentials before terraform init.