{"record":{"id":"795d1be45c9abacc","repo":"ory/kratos","slug":"migrations-have-not-yet-been-fully-applied","errorCode":null,"errorMessage":"migrations have not yet been fully applied","messagePattern":"migrations have not yet been fully applied","errorType":"http","errorClass":null,"httpStatus":503,"severity":"error","filePath":"driver/registry_default.go","lineNumber":300,"sourceCode":"func (m *RegistryDefault) HealthHandler(_ context.Context) *healthx.Handler {\n\tif m.healthxHandler == nil {\n\t\tm.healthxHandler = healthx.NewHandler(m.Writer(), config.Version,\n\t\t\thealthx.ReadyCheckers{\n\t\t\t\t\"database\": func(r *http.Request) error {\n\t\t\t\t\treturn m.PingContext(r.Context())\n\t\t\t\t},\n\t\t\t\t\"migrations\": func(r *http.Request) error {\n\t\t\t\t\tif m.migrationStatus != nil && !m.migrationStatus.HasPending() {\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\n\t\t\t\t\tstatus, err := m.Persister().MigrationStatus(r.Context())\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\n\t\t\t\t\tif status.HasPending() {\n\t\t\t\t\t\treturn errors.Errorf(\"migrations have not yet been fully applied\")\n\t\t\t\t\t}\n\n\t\t\t\t\tm.migrationStatus = status\n\t\t\t\t\treturn nil\n\t\t\t\t},\n\t\t\t})\n\t}\n\n\treturn m.healthxHandler\n}\n\nfunc (m *RegistryDefault) WithCSRFHandler(c nosurf.Handler) {\n\tm.nosurf = c\n}\n\nfunc (m *RegistryDefault) CSRFHandler() nosurf.Handler {\n\tif m.nosurf == nil {\n\t\tpanic(\"csrf handler is not set\")","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/ory/kratos/blob/b86338da04a040247a07f46100a86dcfb3875909/driver/registry_default.go#L282-L318","documentation":"During the service bootstrap pipeline (registry_default.go), a boot check queries the persister's MigrationStatus and, if status.HasPending() is true, refuses to continue with this error. It is a safety gate: the schema is not at the expected migration version, so the service would misbehave against a partially migrated database.","triggerScenarios":"Starting Kratos with a database whose schema migration history has pending migrations — e.g. upgrading to a newer version without running 'kratos migrate sql up', or the migrate command was run partially/against a different database than the one configured in dsn.","commonSituations":"Version upgrade deployments where migrations were skipped in CI, blue/green setups pointing the new binary at the old schema, and local dev where migrations were applied to one sqlite/postgres instance but the app dsn points at another.","solutions":["Run the migration CLI against the configured DSN: 'kratos migrate sql -e DSN up' (or apply the SQL files with your migration tool).","Verify the DSN used for migration matches the DSN the server uses, so you are migrating the right database.","Check 'kratos migrate status -e DSN' to list pending migrations before and after applying.","If the schema is intentionally behind (e.g. replica), point the service at a fully migrated instance."],"exampleFix":"# before (server started with pending migrations)\nkratos serve -c kratos.yml\n\n# after (apply migrations first, then serve)\nkratos migrate sql -e DSN up\nkratos serve -c kratos.yml","handlingStrategy":"try-catch","validationCode":"status, err := m.Persister().MigrationStatus(ctx)\nif err == nil && status.HasPending() {\n    return fmt.Errorf(\"%d pending migrations; run migrations before serving\", len(status.Pending()))\n}","typeGuard":null,"tryCatchPattern":"// in startup code\nif err := run(); err != nil {\n    if strings.Contains(err.Error(), \"migrations have not yet been fully applied\") {\n        // trigger your migration job, then retry startup\n        runMigrations(dsn)\n        return run()\n    }\n    return err\n}","preventionTips":["Run migrations as a separate deployment step/job before rolling out the new server version.","Verify migration status with 'kratos migrate status' in CI before deploying.","Ensure migration jobs and the server use the exact same DSN.","Pin service and schema versions together in upgrade runbooks."],"tags":["database","migrations","startup","schema"],"backgroundTag":"database-schema-out-of-date","analyzedSha":"b86338da04a040247a07f46100a86dcfb3875909","analyzedAt":"2026-09-07T15:58:15.934Z","contentChangedAt":"2026-09-07T15:58:15.934Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}