hashicorp/terraform · error

missing state name

Error message

missing state name

What it means

Returned by (*Backend).remoteClient (internal/backend/remote-state/s3/backend_state.go:158) when the workspace name passed in is empty. remoteClient builds the S3 object key path (and DynamoDB lock path) from the workspace; an empty name would produce a malformed key. The guard fails fast before any AWS API call.

Source

Thrown at internal/backend/remote-state/s3/backend_state.go:158

	if name == backend.DefaultStateName || name == "" {
		return diags.Append(fmt.Errorf("can't delete default state"))
	}

	log.Info("Deleting workspace")

	client, err := b.remoteClient(name)
	if err != nil {
		return diags.Append(err)
	}

	return diags.Append(client.Delete())
}

// 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")
	}

	client := &RemoteClient{
		s3Client:              b.s3Client,
		dynClient:             b.dynClient,
		bucketName:            b.bucketName,
		path:                  b.path(name),
		serverSideEncryption:  b.serverSideEncryption,
		customerEncryptionKey: b.customerEncryptionKey,
		acl:                   b.acl,
		kmsKeyID:              b.kmsKeyID,
		ddbTable:              b.ddbTable,
		skipS3Checksum:        b.skipS3Checksum,
		lockFilePath:          b.getLockFilePath(name),
		useLockFile:           b.useLockFile,
	}

	return client, nil

View on GitHub (pinned to c9def3e214)

Solutions

1. Resolve the workspace name to a non-empty value before calling StateMgr/DeleteWorkspace.
2. Default to backend.DefaultStateName when no workspace is explicitly selected.
3. Validate at the call site and surface a clear error to the caller.

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("") or DeleteWorkspace("", _) on the s3 backend; CLI/wrapper code forwarding an unresolved (empty) workspace; automation reading the workspace from an unset env var.

Common situations: CI with a missing TF_WORKSPACE; migration tooling that doesn't resolve the current workspace; wrapper code that defaults to the zero value instead of "default"; programmatic use of the S3 backend without selecting a workspace.

Related errors

• empty state name
• missing state name
• missing state name
• invalid md5
• can't delete default state

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