hashicorp/terraform · error

workspace not found For security, returns '404 Not Found'…

Error message

workspace %s not found

For security, %s returns '404 Not Found' responses for resources
for resources that a user doesn't have access to, in addition to resources that
do not exist. If the resource does exist, please check the permissions of the provided token.

What it means

fetchWorkspace converts tfe.ErrResourceNotFound from Workspaces.Read into a human-facing message. The message deliberately conflates 'does not exist' with 'exists but forbidden', because TFE/HCP returns 404 for both to avoid leaking resource existence. The workspace name and a permissions hint are included.

Solutions

1. Verify the workspace name spelling and that it exists in the configured organization via the TFE/HCP UI.
2. Confirm TF_WORKSPACE is unset or points at an existing workspace.
3. Check that the API token's team has at least read access on the workspace (404 is returned even when access is the problem).
4. Verify the `hostname` and `organization` fields in the cloud block.

Example fix

# before
export TF_WORKSPACE=Prod-Env

# after
export TF_WORKSPACE=prod-env   # matches actual workspace name

func workspaceExists(client *tfe.Client, org, ws string) error {
    if _, err := client.Workspaces.Read(ctx, org, ws); err != nil {
        if err == tfe.ErrResourceNotFound {
            return fmt.Errorf("workspace %s/%s missing or inaccessible", org, ws)
        }
        return err
    }
    return nil
}
// call during `terraform init` preflight

When it happens

Trigger: b.client.Workspaces.Read(ctx, organization, workspace) returns tfe.ErrResourceNotFound: workspace truly missing in the org; org name misspelled; token has no access and the API masks it as 404; TF_WORKSPACE/`terraform workspace select` resolves to a name that does not exist.

Common situations: Wrong workspace name in cloud block; TF_WORKSPACE env var set to a non-existent workspace; token belongs to a different team with no membership on the workspace; copy-paste error in organization name.

Related errors

• error creating workspace
• error finding remote workspace
• error updating workspace
• failed to create project
• returned an unexpected error

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/99081519cd6f10f6. Report an issue: GitHub.

Appendix: source

Thrown at internal/cloud/backend.go:1336

	hostname         string
	organization     string
	token            string
	workspaceMapping WorkspaceMapping
}

func isLocalExecutionMode(execMode string) bool {
	return execMode == "local"
}

func (b *Cloud) fetchWorkspace(ctx context.Context, organization string, workspace string) (*tfe.Workspace, error) {
	// Retrieve the workspace for this operation.
	w, err := b.client.Workspaces.Read(ctx, organization, workspace)
	if err != nil {
		switch err {
		case context.Canceled:
			return nil, err
		case tfe.ErrResourceNotFound:
			return nil, fmt.Errorf(
				"workspace %s not found\n\n"+
					fmt.Sprintf("For security, %s returns '404 Not Found' responses for resources\n", b.appName)+
					"for resources that a user doesn't have access to, in addition to resources that\n"+
					"do not exist. If the resource does exist, please check the permissions of the provided token.",
				workspace,
			)
		default:
			err := fmt.Errorf(
				"%s returned an unexpected error:\n\n%s",
				b.appName,
				err,
			)
			return nil, err
		}
	}

	return w, nil
}

View on GitHub (pinned to d32a084675)