hashicorp/terraform · error

Invalid workspace name set using %s

Error message

Invalid workspace name set using %s

What it means

A package-level sentinel error (errInvalidWorkspaceNameEnvVar) returned by WorkspaceOverridden() when the TF_WORKSPACE environment variable is set to a value that fails validWorkspaceName(). Terraform deliberately refuses to proceed because an invalid workspace name would corrupt state addressing. The %s expands to the literal env var name TF_WORKSPACE.

Source

Thrown at internal/command/meta.go:773

		if interval, err := strconv.Atoi(val); err == nil && interval > DefaultStatePersistInterval {
			// The user-specified interval must be greater than the default minimum
			return interval
		} else if err != nil {
			log.Printf("[ERROR] Can't parse state persist interval %q of environment variable %q", val, StatePersistIntervalEnvVar)
		}
	}
	return DefaultStatePersistInterval
}

// WorkspaceNameEnvVar is the name of the environment variable that can be used
// to set the name of the Terraform workspace, overriding the workspace chosen
// by `terraform workspace select`.
//
// Note that this environment variable is ignored by `terraform workspace new`
// and `terraform workspace delete`.
const WorkspaceNameEnvVar = "TF_WORKSPACE"

var errInvalidWorkspaceNameEnvVar = fmt.Errorf("Invalid workspace name set using %s", WorkspaceNameEnvVar)

// Workspace returns the name of the currently configured workspace, corresponding
// to the desired named state.
//
// Workspace names are validated via use of the `WorkspaceOverridden` method.
func (m *Meta) Workspace() (string, error) {
	current, _, err := m.WorkspaceOverridden()
	if err != nil {
		return "", err
	}
	return current, nil
}

// WorkspaceOverridden returns the name of the currently configured workspace,
// corresponding to the desired named state, as well as a bool saying whether
// this was set via the TF_WORKSPACE environment variable.
//
// The method also validates the workspace name. If it's invalid, an error is

View on GitHub (pinned to c9def3e214)

Solutions

1. Unset or correct TF_WORKSPACE so it contains only valid workspace name characters.
2. Validate the env var before running Terraform: ensure it matches the allowed workspace name pattern.
3. Use `terraform workspace select <name>` instead of TF_WORKSPACE when the name is dynamic.

Example fix

// before
export TF_WORKSPACE="feature/auth-v2"
// after
export TF_WORKSPACE="feature-auth-v2"

// Validate TF_WORKSPACE before invoking terraform
name := os.Getenv("TF_WORKSPACE")
if name != "" && !arguments.ValidWorkspaceName(name) {
    log.Fatalf("TF_WORKSPACE=%q is not a valid workspace name", name)
}

When it happens

Trigger: TF_WORKSPACE is exported with a value containing illegal characters or matching a reserved name. validWorkspaceName() (delegating to arguments.ValidWorkspaceName) rejects names that are empty, contain path separators, or equal reserved tokens like 'default'.

Common situations: A CI script sets TF_WORKSPACE to a branch name containing '/' or uppercase chars; a user typos TF_WORKSPACE='prod-data/region'; copying a value with spaces or special chars from a secret manager.

Related errors

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

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