{"record":{"id":"029d5137b162284f","repo":"stalwartlabs/stalwart","slug":"unknown-database-schema-version-expected-or-be","errorCode":null,"errorMessage":"Unknown database schema version, expected {} or below, found {}","messagePattern":"Unknown database schema version, expected (.+?) or below, found (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/migration/src/lib.rs","lineNumber":52,"sourceCode":"            }\n        }\n        Some(0..=4) => {\n            abort(concat!(\n                \"You must first upgrade to version 0.15, please read \",\n                \"https://github.com/stalwartlabs/stalwart/blob/main/UPGRADING/v0_16.md\"\n            ));\n        }\n        Some(5) => {\n            if !server.registry().is_recovery_mode() {\n                abort(concat!(\n                    \"Upgrading to version 0.16 is a multi-step process, please read \",\n                    \"https://github.com/stalwartlabs/stalwart/blob/main/UPGRADING/v0_16.md\"\n                ));\n            }\n        }\n\n        Some(version) => {\n            panic!(\n                \"Unknown database schema version, expected {} or below, found {}\",\n                DATABASE_SCHEMA_VERSION, version\n            );\n        }\n        _ => {\n            if is_new_install(server).await.caused_by(trc::location!())? {\n                write_schema_version(server).await?;\n                return Ok(());\n            } else {\n                abort(concat!(\n                    \"You must first upgrade to version 0.15, please read \",\n                    \"https://github.com/stalwartlabs/stalwart/blob/main/UPGRADING/v0_16.md\"\n                ));\n            }\n        }\n    }\n\n    migrate_v0_16(server).await?;","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/stalwartlabs/stalwart/blob/e96200385781a6a9995a8b839ac27d6c75a983ee/crates/migration/src/lib.rs#L34-L70","documentation":"Stalwart's migration tool panics when the database's stored schema version is NEWER than the schema version supported by this binary. Downgrading across schema migrations is unsupported because older code cannot safely read newer table layouts. The panic halts startup/migration before any destructive work is attempted.","triggerScenarios":"Running `try_migrate` against a database whose schema_version row contains a value greater than DATABASE_SCHEMA_VERSION compiled into the binary — i.e. the database was migrated by a newer Stalwart release.","commonSituations":"Rolling back Stalwart from a newer version to an older one after the newer version already migrated the schema; pointing an older container image at a data volume used by a newer deployment.","solutions":["Run the NEWER Stalwart version that matches the database schema version (check UPGRADING docs for the version that wrote that schema).","Restore the database from a backup taken before the newer migration ran, then start the older binary.","Export data with the newer version and re-import into a fresh database initialized by the target version.","Never attempt to hand-edit the schema version row; this will corrupt data."],"exampleFix":"// before: downgrade binary against migrated DB\n// docker run stalwartlabs/stalwart:v0.10  -> panics\n// after: restore pre-migration backup first\n// docker run stalwartlabs/stalwart:v0.9 with restored data volume","handlingStrategy":"validation","validationCode":"// before launching the older binary, compare stored schema version\nlet stored = server.store().get_version().await?;\nif stored > DATABASE_SCHEMA_VERSION {\n    eprintln!(\"DB schema {stored} newer than binary {} — do not start\", DATABASE_SCHEMA_VERSION);\n    std::process::exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin data volumes and binary versions together in deployment manifests.","Snapshot/backup the database before every Stalwart upgrade.","Read UPGRADING notes before changing versions in either direction.","Use immutable image tags; never reuse a data volume across major downgrades."],"tags":["database","migration","schema","downgrade"],"backgroundTag":"schema-validation-failed","analyzedSha":"e96200385781a6a9995a8b839ac27d6c75a983ee","analyzedAt":"2026-09-06T22:07:17.982Z","contentChangedAt":"2026-09-06T22:07:17.982Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}