{"record":{"id":"9039c543bdf413c8","repo":"hashicorp/terraform","slug":"state-migration-failed-w","errorCode":null,"errorMessage":"State migration failed: %w","messagePattern":"State migration failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/state_migrate.go","lineNumber":340,"sourceCode":"\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\tview.LogMigrationDestinationInitializationComplete()\n\n\tview.LogStateMigrationStart(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.LogStateMigrationErrored(views.DuringMigration, source, destination)\n\t\treturn 1\n\t}\n\n\tview.LogStateMigrationComplete()\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\tview.LogStateMigrationErrored(views.DuringLockfile, source, destination)\n\t\t\treturn 1\n\t\t}\n","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/state_migrate.go#L322-L358","documentation":"Top-level wrapper around c.Meta.backendMigrateState(migrateOpts) during state migration. All the prior validation (config serialization, provider install, version checks) passed; the actual copy/move of state objects from source to destination backend failed. The wrapped err carries the migration-specific reason (lock, write, auth).","triggerScenarios":"Source backend readable and destination writable, but the transfer fails: destination write returns 4xx/5xx, lock acquisition on destination times out, source changes mid-migration, network drops during a large state upload.","commonSituations":"Migrating state from local to S3 with wrong KMS key on destination bucket; destination bucket has versioning/acl that rejects the PUT; cross-account migration without object-write IAM; partial upload when the run is interrupted; destination workspace already has state.","solutions":["Read the wrapped err — it names the exact failed operation (PUT, lock, copy).","Confirm destination backend IAM/permissions for write + lock (e.g. s3:PutObject, dynamodb:PutItem).","If destination already has state, decide explicitly: clear it or pick a different destination key.","Re-run after fixing; the migration is designed to be retried safely from source."],"exampleFix":"# before\n terraform state migrate  # fails: AccessDenied on PutObject\n\n# after (grant write on destination)\n aws iam attach-role-policy ... --policy-name S3Write\n terraform state migrate","handlingStrategy":"retry","validationCode":"// Confirm destination writability before invoking migrate.\nif w, ok := dstBackend.(interface{ WriteState(*states.State) error }); ok {\n    if err := w.WriteState(nil); err != nil { return err }\n}","typeGuard":null,"tryCatchPattern":"err := c.Meta.backendMigrateState(migrateOpts)\nif err != nil {\n    diags = diags.Append(fmt.Errorf(\"State migration failed: %w\", err))\n    view.Diagnostics(diags)\n    view.LogStateMigrationErrored(views.DuringMigration, source, destination)\n    // Migration is idempotent from source — safe to retry once.\n    return 1\n}","preventionTips":["Grant destination backend IAM write+lock permissions before migrating.","Back up source state (`terraform state pull`) before migration.","Confirm destination workspace is empty or intentionally overwritten.","Run migrations from a stable network connection to avoid mid-upload drops."],"tags":["terraform","state-migration","backend","iam","lock","io"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}