hashicorp/terraform · error

state name not allow to be empty

Error message

state name not allow to be empty

What it means

Raised by Backend.client() (cos/backend_state.go:156) when the requested workspace/state name is empty or only whitespace. Every state operation requires a concrete name (default is provided by the caller as backend.DefaultStateName).

Source

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

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

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

	return stateMgr, diags
}

// client returns a remoteClient for the named state.
func (b *Backend) client(name string) (*remoteClient, error) {
	if strings.TrimSpace(name) == "" {
		return nil, fmt.Errorf("state name not allow to be empty")
	}

	return &remoteClient{
		cosContext: b.cosContext,
		cosClient:  b.cosClient,
		tagClient:  b.tagClient,
		bucket:     b.bucket,
		stateFile:  b.stateFile(name),
		lockFile:   b.lockFile(name),
		encrypt:    b.encrypt,
		acl:        b.acl,
	}, nil
}

// stateFile returns state file path by name
func (b *Backend) stateFile(name string) string {
	if name == backend.DefaultStateName {
		return path.Join(b.prefix, b.key)

View on GitHub (pinned to c9def3e214)

Solutions

1. Pass a non-empty workspace name, or use 'default' for the default workspace.
2. Default unset workspace variables to 'default' in your scripts before invoking terraform.
3. Validate workspace names upstream before passing them to the backend.

Example fix

// before
WORKSPACE=""
terraform workspace select "$WORKSPACE"
// after
WORKSPACE="${WORKSPACE:-default}"
terraform workspace select "$WORKSPACE"

// Ensure a workspace name is non-empty before backend operations
func validWorkspaceName(name string) error {
    if strings.TrimSpace(name) == "" {
        return fmt.Errorf("state name must not be empty")
    }
    return nil
}

When it happens

Trigger: client("") or client(" ") - strings.TrimSpace(name) == "". Happens when a caller passes an unset workspace variable.

Common situations: A workspace variable resolved to empty in automation; a bug in calling code that did not default to 'default'.

Related errors

• default state is not allowed to be deleted
• prefix must not start with '/' or './'
• key can not start and end with '/'
• acl value invalid, expected %s or %s, got %s
• %q cannot be lower than %d: %d

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