hashicorp/terraform · error

Error migrating the workspace %[1]q from the previous %[2]q

Error message

Error migrating the workspace %[1]q from the previous %[2]q %[3]s
to the newly configured %[4]q %[5]s:
    %[6]s

Terraform copies workspaces in alphabetical order. Any workspaces
alphabetically earlier than this one have been copied. Any workspaces
later than this haven't been modified in the destination. No workspaces
in the source state have been modified.

Please resolve the error above and run the initialization command again.
This will attempt to copy (with permission) all workspaces again.

What it means

During multi-workspace migration to HCP Terraform, each source workspace is migrated individually via backendMigrateState_s_s. If any single workspace's migration fails, this error names the failing workspace and explains the alphabetical-order invariant: workspaces before it in alphabetical order have already been copied, later ones are untouched, and the source is never modified. Re-running init re-attempts all workspaces.

Source

Thrown at internal/command/meta_backend_migrate.go:805

	// Go through each and migrate
	for _, name := range sourceWorkspaces {

		// Copy the same names
		opts.sourceWorkspace = name
		if newName, ok := defaultNewName[name]; ok {
			// this has to be done before setting destinationWorkspace
			name = newName
		}
		opts.destinationWorkspace = strings.Replace(pattern, "*", name, -1)

		// Force it, we confirmed above
		opts.force = true

		// Perform the migration
		log.Printf("[INFO] backendMigrateTFC: multi-to-multi migration, source workspace %q to destination workspace %q", opts.sourceWorkspace, opts.destinationWorkspace)
		if err := m.backendMigrateState_s_s(opts); err != nil {
			return fmt.Errorf(strings.TrimSpace(
				errMigrateMulti), name,
				opts.SourceType, srcWord,
				opts.DestinationType, dstWord, err)
		}

		if currentWorkspace == opts.sourceWorkspace {
			newCurrentWorkspace = opts.destinationWorkspace
		}
	}

	// After migrating multiple workspaces, we need to reselect the current workspace as it may
	// have been renamed. Query the backend first to be sure it now exists.
	workspaces, diags := opts.Destination.Workspaces()
	if diags.HasErrors() {
		return diags.Err()
	}
	if diags.HasWarnings() {
		log.Printf("[WARN] backendMigrateState_S_TFC: warning(s) returned when getting workspaces from destination backend: %s", diags.ErrWithWarnings())

View on GitHub (pinned to d32a084675)

Solutions

1. Read the embedded %[6]s error to identify the specific cause for the failing workspace
2. Resolve the underlying issue (e.g., delete a conflicting workspace, request higher API limits, fix permissions)
3. Re-run `terraform init` to retry — it will re-copy all workspaces with permission prompts
4. If a single workspace is problematic, migrate it separately after the bulk migration completes
5. Check HCP Terraform organization settings for workspace limits or naming policies

Example fix

# before: workspace name conflict causes multi-workspace migration failure
terraform init
# after: resolve conflict, re-run init
terraform workspace delete -force conflicting-name  # in TFC UI/API
terraform init

// Before multi-workspace migration, check destination workspace limits and naming conflicts
func preflightMultiMigration(dest backend.Backend, sourceWorkspaces []string) error {
    existing, diags := dest.Workspaces()
    if diags.HasErrors() {
        return diags.Err()
    }
    existingSet := make(map[string]bool)
    for _, w := range existing {
        existingSet[w] = true
    }
    for _, w := range sourceWorkspaces {
        if existingSet[w] {
            return fmt.Errorf("workspace %q already exists in destination", w)
        }
    }
    return nil
}

// Multi-workspace migration is designed to be retried — re-running init
// re-attempts all workspaces with permission prompts. Wrap with retry logic
// for transient failures (rate limits, network blips):
// for i := 0; i < 3; i++ {
//     err := terraformInit()
//     if err == nil { break }
//     if isTransient(err) { time.Sleep(backoff(i)); continue }
//     return err
// }

When it happens

Trigger: A per-workspace state copy operation fails mid-migration. The error could come from HCP Terraform API rate limiting, workspace creation failure, destination workspace naming conflict, or a transient network error during a specific workspace's state push.

Common situations: HCP Terraform API rate limits hit during bulk workspace migration, workspace name already exists in the destination organization, insufficient permissions on the destination, network blip during a large workspace state upload, or TFC org-level workspace count limits reached.

Related errors

• Error migrating the workspace %[1]q from the previous %[2]q
• Migrating state from HCP Terraform or Terraform Enterprise t
• Error locking state: %s
• Error asking for state migration action: %s
• Migration aborted by user.

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