hashicorp/terraform · error

missing state name

Error message

missing state name

What it means

Returned by (*Backend).remoteClient (internal/backend/remote-state/kubernetes/backend_state.go:156) when the workspace name passed in is empty. remoteClient builds the secret name, labels, and lease name from the workspace, so an empty name would produce invalid Kubernetes resource names downstream. The guard fails fast before any k8s API call.

Source

Thrown at internal/backend/remote-state/kubernetes/backend_state.go:156

		if err := stateMgr.PersistState(nil); err != nil {
			unlockErr := unlock(err)
			return nil, diags.Append(unlockErr)
		}

		// Unlock, the state should now be initialized
		if err := unlock(nil); err != nil {
			return nil, diags.Append(err)
		}

	}

	return stateMgr, diags
}

// get a remote client configured for this state
func (b *Backend) remoteClient(name string) (*RemoteClient, error) {
	if name == "" {
		return nil, errors.New("missing state name")
	}

	secretClient, err := b.KubernetesSecretClient()
	if err != nil {
		return nil, err
	}

	leaseClient, err := b.KubernetesLeaseClient()
	if err != nil {
		return nil, err
	}

	client := &RemoteClient{
		kubernetesSecretClient: secretClient,
		kubernetesLeaseClient:  leaseClient,
		namespace:              b.namespace,
		labels:                 b.labels,
		nameSuffix:             b.nameSuffix,

View on GitHub (pinned to c9def3e214)

Solutions

1. Ensure the workspace name is resolved to a non-empty value before calling StateMgr/DeleteWorkspace.
2. Default to backend.DefaultStateName ("default") when no workspace is selected.
3. Validate workspace name != "" at the call site and surface a clear upstream error.

Example fix

// before
client, err := b.remoteClient(ws) // ws == ""

// after
if ws == "" {
    ws = backend.DefaultStateName
}
client, err := b.remoteClient(ws)

if name == "" {
    name = backend.DefaultStateName
}
client, err := b.remoteClient(name)

When it happens

Trigger: Calling StateMgr(""), DeleteWorkspace("", _), or any path through remoteClient with an unresolved workspace; CLI/wrapper code that forwards an empty TF_WORKSPACE or current workspace to the kubernetes backend.

Common situations: Automation that reads the workspace from an unset env var; migrating configs where the workspace block is missing; bugs in workspace resolution that yield "" before the k8s backend is invoked.

Related errors

• empty state name
• the secret name %v is invalid, {validationErrors} This is a
• missing state name
• missing state name
• default workspace not supported You can create a new workspa

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