{"record":{"id":"9039c543bdf413c8","repo":"hashicorp/terraform","slug":"state-migration-failed-w","errorCode":null,"errorMessage":"State migration failed: %w","messagePattern":"State migration failed: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/command/state_migrate.go","lineNumber":336,"sourceCode":"\t\tdiags = diags.Append(tfdiags.Sourceless(\n\t\t\ttfdiags.Error,\n\t\t\t\"Unknown migration destination\",\n\t\t\t\"No configuration was provided for where to migrate the state to. Please ensure that a file with a .tf extension is present and contains valid state_store or backend configuration inside the terraform block.\",\n\t\t))\n\t}\n\n\t// present all errors from above together so user can fix them all at once\n\tif diags.HasErrors() {\n\t\tview.Diagnostics(diags)\n\t\treturn 1\n\t}\n\n\tview.Log(views.StateMigrationStartMessage, source, destination)\n\n\t// Perform the migration from source to destination\n\terr := c.Meta.backendMigrateState(migrateOpts)\n\tif err != nil {\n\t\tdiags = diags.Append(fmt.Errorf(\"State migration failed: %w\", err))\n\t\tview.Diagnostics(diags)\n\t\tview.Log(views.StateMigrationFailureMessage, source, destination)\n\t\treturn 1\n\t}\n\n\t// After a successful migration to a state store, we must make sure the dependency lock file contains the\n\t// details of the destination state store provider.\n\tif rootMod.StateStore != nil {\n\t\toriginalLocks, originalLockDiags := c.lockedDependencies()\n\t\tdiags = diags.Append(originalLockDiags)\n\t\tif originalLockDiags.HasErrors() {\n\t\t\tview.Diagnostics(diags)\n\t\t\treturn 1\n\t\t}\n\n\t\t// Get the combination of locks\n\t\t//\n\t\t// Take the lock from the destination provider download and add in the original locks from the dependency lock file.","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/state_migrate.go#L318-L354","documentation":"The top-level failure returned by `terraform state migrate` when Meta.backendMigrateState(migrateOpts) returns an error. backendMigrateState is the orchestrator that copies state from the source backend to the destination backend; any failure in locking, reading source state, writing destination state, or backend-specific transfer surfaces here wrapped as %w. The preceding view.Log already printed StateMigrationFailureMessage naming source and destination.","triggerScenarios":"Running `terraform state migrate` where the actual state transfer fails: source backend cannot acquire/release its state lock, destination backend write/lock fails, network/auth error to S3/cloud/HTTP backend, or incompatible backend implementations.","commonSituations":"Migrating to S3 without bucket write/IAM permissions; state lock held by another running operation; stale lock from a crashed run; HCP/TFE token expired or lacking workspace access; cross-region bucket misconfiguration; concurrent applies holding the lock.","solutions":["Read the wrapped %w — it states the concrete failure (lock, auth, write).","If the lock is stuck from a crashed process, force-unlock: `terraform force-unlock <LOCK_ID>`.","Verify destination backend credentials and write permissions, then re-run `terraform state migrate`.","Ensure no other Terraform process is operating on the same state, then retry."],"exampleFix":"# before - migrating while a stale lock remains\nterraform state migrate\n# State migration failed: Failed to lock state: lock info...\n\n# after\nterraform force-unlock <LOCK_ID>\nterraform state migrate","handlingStrategy":"retry","validationCode":"// pre-flight: confirm source lock is free and destination is writable.\n// (Backend-specific; example for local lock file)\nfunc lockIsFree(path string) bool {\n    _, err := os.Stat(path + \".tflock\")\n    return os.IsNotExist(err)\n}","typeGuard":null,"tryCatchPattern":"// retry transient migration failures (lock contention / network) with backoff\nfor attempt := 0; attempt < 3; attempt++ {\n    if err := backendMigrateState(opts); err != nil {\n        if isTransient(err) {\n            time.Sleep(backoff(attempt))\n            continue\n        }\n        return err\n    }\n    break\n}","preventionTips":["Ensure no other Terraform process runs against the same state during migration.","Verify destination backend credentials/permissions before migrating.","Force-unlock stale locks from crashed runs before retrying.","Run migrations during a maintenance window to avoid lock contention."],"tags":["state-migrate","backend","state-lock","migration"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}