{"record":{"id":"f2ab3371d8a4d004","repo":"ory/hydra","slug":"problem-inserting-migration-version-s-your-datab","errorCode":null,"errorMessage":"problem inserting migration version %s. YOUR DATABASE MAY BE IN AN INCONSISTENT STATE! MANUAL INTERVENTION REQUIRED!","messagePattern":"problem inserting migration version (.+?)\\. YOUR DATABASE MAY BE IN AN INCONSISTENT STATE! MANUAL INTERVENTION REQUIRED!","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"oryx/popx/migrator.go","lineNumber":245,"sourceCode":"\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tl.Info(\"Migration has not yet been applied, running migration.\")\n\n\t\t\tif err := mi.Valid(); err != nil {\n\t\t\t\treturn errors.WithStack(err)\n\t\t\t}\n\n\t\t\tnoTx := mb.shouldNotUseTransaction(mi)\n\t\t\tif noTx {\n\t\t\t\tl.Info(\"NOT running migrations inside a transaction\")\n\t\t\t\tif err := mi.Runner(mi, c); err != nil {\n\t\t\t\t\treturn errors.WithStack(err)\n\t\t\t\t}\n\n\t\t\t\t// #nosec G201 - mtn is a system-wide const\n\t\t\t\tif err := c.RawQuery(fmt.Sprintf(\"INSERT INTO %s (version) VALUES (?)\", mtn), mi.Version).Exec(); err != nil {\n\t\t\t\t\treturn errors.Wrapf(err, \"problem inserting migration version %s. YOUR DATABASE MAY BE IN AN INCONSISTENT STATE! MANUAL INTERVENTION REQUIRED!\", mi.Version)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tif err := mb.isolatedTransaction(ctx, \"up\", func(conn *pop.Connection) error {\n\t\t\t\t\tif err := mi.Runner(mi, conn); err != nil {\n\t\t\t\t\t\treturn errors.WithStack(err)\n\t\t\t\t\t}\n\n\t\t\t\t\t// #nosec G201 - mtn is a system-wide const\n\t\t\t\t\tif err := conn.RawQuery(fmt.Sprintf(\"INSERT INTO %s (version) VALUES (?)\", mtn), mi.Version).Exec(); err != nil {\n\t\t\t\t\t\treturn errors.Wrapf(err, \"problem inserting migration version %s\", mi.Version)\n\t\t\t\t\t}\n\t\t\t\t\treturn nil\n\t\t\t\t}); err != nil {\n\t\t\t\t\treturn errors.WithStack(err)\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tl.WithField(\"autocommit\", noTx).Infof(\"> %s applied successfully\", mi.Name)","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/ory/hydra/blob/4174065ffb052799890f7480f5360a877a67ffc1/oryx/popx/migrator.go#L227-L263","documentation":"When a migration is marked as no-transaction (shouldNotUseTransaction), the schema change runs outside a transaction; if the subsequent INSERT of the version row into schema_migration fails, the schema change has already been applied but not recorded, leaving the database in a partially migrated state. The library flags this explicitly as requiring manual intervention because it cannot roll back automatically.","triggerScenarios":"Running an Up migration whose Runner is configured to run without a transaction (e.g. migration annotations like NO-TX, or dialects such as MySQL where DDL is non-transactional), and the INSERT INTO schema_migration fails after the migration body succeeded.","commonSituations":"Connection drop or timeout right after a long DDL migration; MySQL DDL implicit commits; DB lock on schema_migration table; disk full; insufficient INSERT privileges.","solutions":["Manually verify whether the migration's schema changes were applied (compare against the migration SQL)","If the schema change exists, manually INSERT the missing version row: INSERT INTO schema_migration (version) VALUES ('<version>');","If the schema change did not apply, fix the underlying cause (connection, locks, privileges) and re-run migrations","Prefer transactional migrations for dialects that support transactional DDL to avoid this state"],"exampleFix":"// before: re-running migrations blindly\n// $ app migrate up\n// after: reconcile first, then re-run\n// SELECT 1 FROM schema_migration WHERE version='20221012101010';\n// INSERT INTO schema_migration (version) VALUES ('20221012101010'); -- if schema applied","handlingStrategy":"validation","validationCode":"// before running no-tx migrations, verify tracking table writability\nif err := db.RawQuery(\"SELECT 1 FROM schema_migration LIMIT 1\").Exec(); err != nil {\n    return fmt.Errorf(\"schema_migration unreadable, refusing no-tx migrate: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := box.Up(ctx, -1); err != nil {\n    if strings.Contains(err.Error(), \"MANUAL INTERVENTION REQUIRED\") {\n        // compare applied schema against migration SQL, insert missing version row or re-run\n    }\n    return err\n}","preventionTips":["Avoid NO-TX migrations unless required; prefer transactional DDL-capable databases (Postgres)","Take a DB backup/snapshot before running migrations","Keep connection timeouts generous for long DDL migrations","Monitor for connection drops during migration windows"],"tags":["database","migration","data-consistency","go"],"backgroundTag":"inconsistent-migration-state","analyzedSha":"4174065ffb052799890f7480f5360a877a67ffc1","analyzedAt":"2026-09-03T14:52:41.581Z","contentChangedAt":"2026-09-03T14:52:41.581Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}