hashicorp/terraform · error

Error loading state: %[3]s Terraform failed to load the

Error message

Error loading state:
    %[3]s

Terraform failed to load the default state from the %[1]q %[2]s.
State migration cannot occur unless the state can be loaded.
State migration has been aborted. The state in both the
source and the destination remain unmodified. Please resolve the
above error and try again.

What it means

During TFC migration with a single default workspace, Terraform calls opts.Source.StateMgr(backend.DefaultStateName) to obtain a state manager for the default workspace. If this call returns diagnostics with errors (sDiags.HasErrors()), the state manager cannot be constructed and migration aborts. Both source and destination states remain unmodified.

Source

Thrown at internal/command/meta_backend_migrate.go:736

	srcWord := backendHumanName(opts.Source)
	dstWord := backendHumanName(opts.Destination)

	// This map is used later when doing the migration per source/destination.
	// If a source has 'default' and has state, then we ask what the new name should be.
	// And further down when we actually run state migration for each
	// source/destination workspace, we use this new name (where source is 'default')
	// and set as destinationWorkspace. If the default workspace does not have
	// state we will not prompt the user for a new name because empty workspaces
	// do not get migrated.
	defaultNewName := map[string]string{}
	for i := 0; i < len(sourceWorkspaces); i++ {
		if sourceWorkspaces[i] == backend.DefaultStateName {
			// For the default workspace we want to look to see if there is any state
			// before we ask for a workspace name to migrate the default workspace into.
			sourceState, sDiags := opts.Source.StateMgr(backend.DefaultStateName)
			if sDiags.HasErrors() {
				return fmt.Errorf(strings.TrimSpace(
					errMigrateSingleLoadDefault), opts.SourceType, srcWord, sDiags.Err())
			}
			// RefreshState is what actually pulls the state to be evaluated.
			if err := sourceState.RefreshState(); err != nil {
				return fmt.Errorf(strings.TrimSpace(
					errMigrateSingleLoadDefault), opts.SourceType, srcWord, err)
			}
			if !sourceState.State().Empty() {
				newName, err := m.promptNewWorkspaceName(opts.DestinationType, dstWord)
				if err != nil {
					return err
				}
				defaultNewName[sourceWorkspaces[i]] = newName
			}
		}
	}

	// Fetch the pattern that will be used to rename the workspaces for HCP Terraform or Terraform Enterprise.

View on GitHub (pinned to d32a084675)

Solutions

1. Check for and force-unlock any stale state locks in the source backend (`terraform force-unlock` if applicable)
2. Verify source backend authentication is working and credentials have not expired
3. Confirm the state storage path/key/bucket configuration is correct and accessible
4. Test the backend connection independently (e.g., `aws s3 ls` for S3 backends) before retrying `terraform init`
5. Clear any local backend cache with `terraform init -reconfigure` if the backend config was recently edited

Example fix

# before: state lock or auth error blocks default state load
terraform init
# after: unlock and retry
terraform force-unlock <LOCK_ID> && terraform init

// Verify state manager can be constructed for the default workspace before migration
func checkStateMgr(back backend.Backend, workspace string) error {
    sm, diags := back.StateMgr(workspace)
    if diags.HasErrors() {
        return fmt.Errorf("cannot construct state manager for %q: %w", workspace, diags.Err())
    }
    _ = sm // state manager is ready
    return nil
}

When it happens

Trigger: Running `terraform init` after reconfiguring the backend when the source backend cannot initialize its state manager for the default workspace — typically due to authentication, lock contention, or configuration errors at the state manager level.

Common situations: Locked state in the source backend (another Terraform process is running), stale or rotated credentials, backend configuration mismatch (wrong path/key in state storage), permissions changed on the state storage object, or the backend service is degraded.

Related errors

• Error locking state: %s
• Error inspecting states in the %q %s: %s Prior to migra
• No state file was found! State management commands require
• error loading state: %w
• Error selecting workspace: %s

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