hashicorp/terraform · error

Failed to select a workspace

Error message

Failed to select a workspace: %w

What it means

On the first-time state_store init path, when selectWorkspace fails with any error OTHER than errBackendNoExistingWorkspaces, that error is wrapped here. It represents the state-store provider rejecting workspace selection/verification (auth, connectivity, or a custom workspace error from the provider).

Solutions

1. Read inner %w for the provider-specific workspace error (auth, 404, network).
2. Fix provider credentials/endpoint in the state_store provider_config block, then re-init.
3. Create the missing workspace (`tofu workspace new <name>`) or switch to one that exists.
4. If the store legitimately has no workspaces and you want the default, ensure TF_WORKSPACE is unset so selectWorkspace takes the empty-store path instead.

Example fix

// before
state_store "acme" {
  provider = "example.com/acme/storage"
  provider_config { token = "wrong" }
}
tofu init  # -> Failed to select a workspace

// after: correct credentials / target an existing workspace
state_store "acme" {
  provider = "example.com/acme/storage"
  provider_config { token = "correct" }
}
tofu init

// Before init, verify the selected workspace exists (or is the default) in the
// state store, so selectWorkspace does not fail.
func workspaceExistsOrIsDefault(b backend.Backend, want string) error {
    if want == backend.DefaultStateName { return nil }
    s, err := b.Workspaces()
    if err != nil { return fmt.Errorf("cannot list workspaces: %w", err) }
    for _, w := range s { if w == want { return nil } }
    return fmt.Errorf("workspace %q does not exist; create with 'tofu workspace new %s'", want, want)
}

if err := m.selectWorkspace(b); err != nil {
    if errors.Is(err, &errBackendNoExistingWorkspaces{}) {
        // handled by default-workspace check elsewhere
    } else {
        if isAuthErr(err) {
            diags = diags.Append(fmt.Errorf("Failed to select a workspace (check provider credentials): %w", err))
        } else {
            diags = diags.Append(fmt.Errorf("Failed to select a workspace: %w", err))
        }
    }
}

When it happens

Trigger: selectWorkspace(b) returns a non-empty-workspaces error during state_store init. Triggers: provider cannot list/verify workspaces (auth failure, endpoint down), the selected workspace does not exist and is not the default, or the provider's Workspaces API errored.

Common situations: Wrong/insufficient provider credentials for the workspace API; the named workspace was deleted out-of-band; provider endpoint misconfigured or temporarily unreachable; selecting a custom workspace that was never created.

Related errors

• Failed to check current workspace
• State store provider
• attempted to encode a malformed backend state file…
• authentication signature from unknown issuer
• encountered a malformed backend state file that contains…

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

Appendix: 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 d32a084675)