hashicorp/terraform · error

Failed to set new workspace: %s

Error message

Failed to set new workspace: %s

What it means

Returned inside the closure in backendMigrateState_s_s when the destination backend doesn't support a default workspace (ErrDefaultWorkspaceNotSupported), the user is prompted for a new name, and then m.SetWorkspace(opts.destinationWorkspace) fails at line 310. The migration was about to use a named workspace but the local workspace selector could not be switched.

Source

Thrown at internal/command/meta_backend_migrate.go:311

					return nil, err
				}

				// Update the name of the destination state.
				opts.destinationWorkspace = name

				destinationState, sDiags := opts.Destination.StateMgr(opts.destinationWorkspace)
				if sDiags.HasErrors() {
					return nil, sDiags.Err()
				}

				// Ignore invalid workspace name as it is irrelevant in this context.
				workspace, _ := m.Workspace()

				// If the currently selected workspace is the default workspace, then set
				// the named workspace as the new selected workspace.
				if workspace == backend.DefaultStateName {
					if err := m.SetWorkspace(opts.destinationWorkspace); err != nil {
						return nil, fmt.Errorf("Failed to set new workspace: %s", err)
					}
				}

				return destinationState, nil
			}()
		} else {
			// For any other error, return it immediately to avoid nil pointer dereference
			return fmt.Errorf(strings.TrimSpace(
				errMigrateSingleLoadDefault), opts.DestinationType, sDiags.Err())
		}
	}
	if err != nil {
		return fmt.Errorf(strings.TrimSpace(
			errMigrateSingleLoadDefault), opts.DestinationType, err)
	}
	if err := destinationState.RefreshState(); err != nil {
		return fmt.Errorf(strings.TrimSpace(
			errMigrateSingleLoadDefault), opts.DestinationType, err)

View on GitHub (pinned to c9def3e214)

Solutions

1. Inspect the inner %s for SetWorkspace's specific reason (invalid name, write error).
2. Ensure the .terraform/ directory is writable by the current user.
3. If the name was invalid, re-run init and provide a valid workspace name (alphanumeric, hyphens).
4. Free disk space if /tmp or the working directory is full.
5. Pre-create the named workspace in the destination and select it with 'terraform workspace select' before migrating.

Example fix

// before: prompt returns 'my workspace' (space invalid)
//   Failed to set new workspace: workspace name contains invalid characters
// after: use a valid name
//   (re-run init) -> enter 'my-workspace'

# Ensure .terraform is writable and pre-supply a valid named workspace.
mkdir -p .terraform && touch .terraform/.writetest && rm .terraform/.writetest \
  || { echo '.terraform not writable'; exit 1; }
# For cloud destinations, set an explicit workspace name to skip the prompt:
# cloud { workspaces { name = "prod" } }

# Detect the SetWorkspace failure and guide the operator.
terraform init 2>/tmp/init.err || rc=$?
if grep -q 'Failed to set new workspace' /tmp/init.err; then
  echo 'SetWorkspace failed — provide a valid workspace name or fix .terraform perms' >&2
fi
exit ${rc:-0}

When it happens

Trigger: Destination backend (e.g., cloud/remote) requires named workspaces, the prompt succeeded yielding a name, but SetWorkspace rejected that name — invalid characters, name already in an inconsistent state, or the local workspace metadata file (.terraform/terraform.tfstate) is unwritable. Wrapped at line 311.

Common situations: User types a workspace name with invalid characters at the prompt; the .terraform directory is read-only or deleted between prompt and SetWorkspace; disk full; running in a container with a read-only mounted workspace directory.

Related errors

• Error migrating the workspace %q from the previous %q backen
• Error loading state: %[2]s Terraform failed to load the
• Error copying state from the previous %q backend to the newl
• Can't ask approval for state migration when interactive inpu
• Migrating state from HCP Terraform or Terraform Enterprise t

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