{"record":{"id":"327aaef570682ca4","repo":"immich-app/immich","slug":"errormessages-schemadrift-or-run-immich-admin-schema-check","errorCode":null,"errorMessage":"${ErrorMessages.SchemaDrift} or run `immich-admin schema-check`","messagePattern":"(.+?) or run `immich-admin schema-check`","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"server/src/services/database.service.ts","lineNumber":137,"sourceCode":"        if (migrationCount > 0) {\n          preparation.push(this.databaseRepository.vacuum({ analyze: true }));\n        }\n      }\n      preparation.push(\n        this.databaseRepository.prewarm(VectorIndex.Clip),\n        this.databaseRepository.prewarm(VectorIndex.Face),\n      );\n      await Promise.all(preparation);\n    });\n  }\n\n  private async checkSchemaDrift() {\n    this.logger.log('Checking for schema drift');\n    const drift = await this.databaseRepository.getSchemaDrift();\n    if (drift.items.length === 0) {\n      this.logger.log('No schema drift detected');\n    } else {\n      this.logger.warn(`${ErrorMessages.SchemaDrift} or run \\`immich-admin schema-check\\``);\n      for (const warning of drift.asHuman()) {\n        this.logger.warn(`  - ${warning}`);\n      }\n    }\n  }\n\n  private async createExtension(extension: DatabaseExtension) {\n    try {\n      await this.databaseRepository.createExtension(extension);\n    } catch (error) {\n      const name = EXTENSION_NAMES[extension];\n      this.logger.fatal(messages.createFailed({ name, extension }));\n      throw error;\n    }\n  }\n\n  private async updateExtension(extension: VectorExtension, availableVersion: string) {\n    this.logger.log(`Updating ${EXTENSION_NAMES[extension]} extension to ${availableVersion}`);","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/database.service.ts#L119-L155","documentation":"During bootstrap, checkSchemaDrift compares the live database schema against the migrations the server expects (getSchemaDrift). If drift is detected — schema changes not produced by Immich's own migrations — the server logs this warning pointing to ErrorMessages.SchemaDrift and `immich-admin schema-check`, then lists each drifted item. The service still starts, but data integrity or future migrations may break.","triggerScenarios":"onBootstrap -> checkSchemaDrift finds drift.items.length > 0 from databaseRepository.getSchemaDrift().","commonSituations":"Database modified by hand (SQL/ORM edits); restoring a dump from a different Immich version; partially applied migrations after a crash; external tools altering tables; downgraded server against a newer schema.","solutions":["Run `immich-admin schema-check` (or equivalent) to see the detailed drift list.","Restore the database from a backup taken before the manual changes.","Reconcile by reverting manual schema edits; never hand-edit Immich tables.","Ensure server version matches the database's migration history; re-run migrations cleanly.","If drift is understood and intentional, restore Immich-managed state before upgrading."],"exampleFix":"// before (manual edit)\nALTER TABLE assets DROP COLUMN \"livePhotoVideoId\";\n// after (use supported API)\n-- do not edit schema manually; downgrade via Immich version or restore backup","handlingStrategy":"validation","validationCode":"# before upgrading, confirm schema matches expected migrations\nimmich-admin schema-check","typeGuard":null,"tryCatchPattern":"try {\n  await bootstrap();\n} catch (e) {\n  if (String(e).includes('schema')) {\n    console.error('Schema drift detected; restore backup or revert manual DB edits before continuing');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Never hand-edit the Immich database schema; use supported settings/APIs only.","Take a database backup before every version upgrade or downgrade.","Restore dumps only into the matching server version.","Run schema-check as part of upgrade runbooks."],"tags":["database","schema","migrations"],"backgroundTag":"schema-validation-failed","analyzedSha":"e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}