🏗️ Terraform Error: HCP Terraform cloud block workspace not found

Exact Error Message

╷
│ Error: Workspace does not exist
│
│ The currently selected workspace (my-app-prod) does not exist. This is
│ expected behaviour when the corresponding workspace has not been created
│ yet in the remote system, or has not been assigned to this configuration.
│
│ To create a workspace, use the "tfe" provider, run "terraform login", or
│ create it in the HCP Terraform UI.
╵

A related authorization variant appears when the token cannot see the org or workspace:

│ Error: Failed to read organization "acme"
│
│ The request failed with 404 Not Found. This may indicate the
│ organization does not exist or you are not authorized to access it.

What It Means

The cloud {} block binds your configuration to a workspace in HCP Terraform (formerly Terraform Cloud) or Terraform Enterprise. During terraform init, Terraform contacts the platform, authenticates with your token, and looks up the named workspace or the workspaces matching your tags.

Workspace does not exist means Terraform authenticated but could not find the target workspace under the given organization. Failed to read organization ... 404 means the organization name is wrong or your token has no access. Both are configuration/authorization problems in the cloud block or your credentials, not a problem with your resources.

Common Causes

• The name or tags under cloud { workspaces { ... } } does not match any existing workspace.
• The organization value is misspelled or points to an org your token cannot access.
• The workspace simply has not been created yet in the HCP Terraform UI or via the tfe provider.
• Your API token is missing, expired, or scoped to a different organization (terraform login never run).
• You mixed name and tags incorrectly — a name-bound config points at a single workspace, while tags map to many.

Diagnostic Commands

Show your cloud block configuration:

grep -A6 'cloud {' *.tf

Confirm you have a stored credential for the host:

grep -A3 'app.terraform.io' ~/.terraform.d/credentials.tfrc.json

Test token and org access via the HCP Terraform API:

curl -s --header "Authorization: Bearer $TF_TOKEN" \
  https://app.terraform.io/api/v2/organizations/acme/workspaces | jq '.data[].attributes.name'

Reproduce the failure during init:

terraform init

Step-by-Step Resolution

1. Verify the organization and workspace name in the cloud block exactly match HCP Terraform (names are case-sensitive):

terraform {
  cloud {
    organization = "acme"

    workspaces {
      name = "my-app-prod"
    }
  }
}

2. Authenticate so Terraform has a valid token for the host:

terraform login

3. Confirm the workspace actually exists. List workspaces via the API, or create it in the UI or with the tfe provider:

curl -s --header "Authorization: Bearer $TF_TOKEN" \
  https://app.terraform.io/api/v2/organizations/acme/workspaces | jq '.data[].attributes.name'

4. If you use tag-based selection, ensure the workspaces exist and carry those tags, and do not also set name:

    workspaces {
      tags = ["app:my-app", "env:prod"]
    }

5. If the token is org-scoped or a team token, confirm it has access to the organization named in the block. Regenerate a correctly scoped token if the 404 persists on the organization read.

6. Re-run init to bind the workspace:

terraform init

Initializing HCP Terraform...
Terraform Cloud has been successfully initialized!

Prevention

• Keep the organization and workspace name/tags in the cloud block under review — a typo or a renamed workspace breaks every run.
• Create the workspace before the first init, either in the UI or declaratively with the tfe_workspace resource.
• Use a token with explicit access to the target organization; prefer team or project tokens scoped to exactly what the config needs.
• Choose either name (single workspace) or tags (many workspaces) deliberately, and never set both.
• Store the token via terraform login or TF_TOKEN_app_terraform_io rather than hardcoding it. The Terraform Cloud prompts can help you scaffold a correct cloud block and matching tfe_workspace resources.

Related Errors

• Required token could not be found — no credential stored for the host; run terraform login.
• 401 Unauthorized from the remote backend — the token is invalid or expired.
• Currently selected workspace ... does not exist — the tag/name selection matched nothing.
• No workspaces are marked for use — a tag-based config where no matching workspace exists yet.

Frequently Asked Questions

Why does init say the workspace does not exist when I can see it in the UI? The most common cause is a case or spelling mismatch between the name in your cloud block and the actual workspace, or your token belonging to a different organization. Compare both exactly.

How do I authenticate to HCP Terraform from the CLI? Run terraform login, which stores a token in ~/.terraform.d/credentials.tfrc.json. Alternatively set the TF_TOKEN_app_terraform_io environment variable.

Should I use name or tags in the workspaces block? Use name to bind a single workspace and tags to map one configuration across many workspaces. Setting both is invalid and causes selection errors.

Can Terraform create the workspace for me? The cloud block will not create it, but a tfe_workspace resource (via the tfe provider) can manage workspaces declaratively, or you can create one in the UI. For more remote-backend guides, see the Terraform guides.