hashicorp/terraform · error

Invalid workspace name set using

Error message

Invalid workspace name set using %s

What it means

Defined as the package-level `errInvalidWorkspaceNameEnvVar` sentinel and returned from `WorkspaceOverridden` when the `TF_WORKSPACE` environment variable is set to a value that fails `validWorkspaceName`. The error message interpolates the env var name (`TF_WORKSPACE`) so the user knows exactly which variable to fix. Because it is a package var (not created inline), callers can compare against it by reference.

Solutions

1. Set `TF_WORKSPACE` to a value containing only letters, digits, dashes, and underscores (no slashes, dots, or spaces).
2. If you need a branch-derived name, sanitize it first: `export TF_WORKSPACE=$(echo "$BRANCH" | tr '/.' '__')`.
3. Unset the variable (`unset TF_WORKSPACE`) and select the workspace explicitly with `terraform workspace select`.
4. Check `.env` files or CI variable settings for stray characters.

Example fix

# before
export TF_WORKSPACE="feature/login"
# after
export TF_WORKSPACE="feature_login"

// Validate TF_WORKSPACE before any terraform command.
if name := os.Getenv("TF_WORKSPACE"); name != "" && !arguments.ValidWorkspaceName(name) {
    return fmt.Errorf("TF_WORKSPACE=%q is invalid; use letters, digits, '-', '_' only", name)
}

// arguments.ValidWorkspaceName is the canonical guard.
func validWs(s string) bool { return arguments.ValidWorkspaceName(s) }

// Compare against the sentinel for targeted handling.
if errors.Is(err, errInvalidWorkspaceNameEnvVar) {
    // tell the user to fix/unset TF_WORKSPACE
}

When it happens

Trigger: `os.Getenv("TF_WORKSPACE")` returns a non-empty string, and `arguments.ValidWorkspaceName(envVar)` returns false. `validWorkspaceName` rejects names that require path escaping or contain characters unsafe for filesystem paths / state identifiers (slashes, dots, etc., per the `arguments` package rules).

Common situations: Export `TF_WORKSPACE=feature/x` (contains a slash); `TF_WORKSPACE=my.ws` or other punctuation; a CI pipeline sets `TF_WORKSPACE` from a git branch name verbatim; copy-paste introduces a leading/trailing space or quote.

Related errors

• can't set both encryption_key and kms_encryption_key
• Cannot set both 'source' and 'content'
• Couldn't create initial workspace: no name provided
• Failed to select workspace: input not a valid number
• host for provisioner cannot be empty

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

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