hashicorp/terraform · error

Failed to select a workspace: %w

Error message

Failed to select a workspace: %w

What it means

In Meta.stateStore_C_s (meta_backend.go:2317), the catch-all branch for selectWorkspace errors that are NOT errBackendNoExistingWorkspaces. selectWorkspace verifies the configured/selected workspace exists in the state store; any failure other than 'no workspaces exist at all' surfaces here (e.g. the backend's Workspaces() call to list/verify errored, or the workspace listing itself failed).

Source

Thrown at internal/command/meta_backend.go:2317

					// So here, we will just ignore the error.
				} else {
					// User needs to run a `terraform workspace new` command to create the missing custom workspace.
					diags = append(diags, tfdiags.Sourceless(
						tfdiags.Error,
						fmt.Sprintf("Workspace %q has not been created yet", ws),
						fmt.Sprintf("State store %q in provider %s (%q) reports that no workspaces currently exist. To create the custom workspace %q use the command `terraform workspace new %s`.",
							c.Type,
							c.Provider.Name,
							c.ProviderAddr,
							ws,
							ws,
						),
					))
					return nil, diags
				}
			} else {
				// For all other errors, report via diagnostics
				diags = diags.Append(fmt.Errorf("Failed to select a workspace: %w", err))
			}
		}
	}
	if diags.HasErrors() {
		return nil, diags
	}

	// Update backend state file
	if err := backendSMgr.WriteState(s); err != nil {
		diags = diags.Append(errBackendWriteSavedDiag(err))
		return nil, diags
	}
	if err := backendSMgr.PersistState(); err != nil {
		diags = diags.Append(errBackendWriteSavedDiag(err))
		return nil, diags
	}

	return b, diags

View on GitHub (pinned to c9def3e214)

Solutions

1. Read the wrapped `%w` for the backend-specific cause (auth, 403, network, not-found).
2. Verify state-store credentials and that the principal can list/read the configured store/path.
3. Confirm the workspace name is valid and exists: `terraform workspace list` / `terraform workspace select <name>`.
4. Retry after resolving connectivity/auth; transient store errors are often intermittent.

Example fix

// before: terraform init   (fails: Failed to select a workspace: AccessDenied)
// after: # grant list/get on the state store, then
terraform init

// Before init, confirm the state store can list workspaces with the configured credentials.
func stateStoreCanListWorkspaces(b backend.Backend) error {
    diags := b.Workspaces()
    if diags.HasErrors() { return diags.Err() }
    return nil
}

// Transient backend errors enumerating workspaces are often worth one retry.
if err := cmd.Init(); err != nil && strings.Contains(err.Error(), "Failed to select a workspace") {
    time.Sleep(backoff); return cmd.Init()
}

When it happens

Trigger: The state-store backend returned an error enumerating or verifying workspaces (auth, network, permissions on the remote store); a workspace name that exists but cannot be read due to store-side issues.

Common situations: Wrong/expired credentials for the state store, a misconfigured store endpoint, insufficient IAM/bucket/object permissions, or a transient outage of the storage backend.

Related errors

• Failed to get existing workspaces: %s
• Failed to check current workspace: %w
• default workspace not supported You can create a new workspa
• workspaces not supported
• empty state name

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/834d5a545a806369. Report an issue: GitHub.