{"record":{"id":"e0dc682901346cdb","repo":"immich-app/immich","slug":"detected-an-inconsistent-media-location-for-more","errorCode":null,"errorMessage":"Detected an inconsistent media location. For more information, see https://docs.immich.app/errors#inconsistent-media-location","messagePattern":"Detected an inconsistent media location\\. For more information, see https://docs\\.immich\\.app/errors#inconsistent-media-location","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"server/src/services/storage.service.ts","lineNumber":118,"sourceCode":"      const savedValue = await this.systemMetadataRepository.get(SystemMetadataKey.MediaLocation);\n      if (samples.length > 0) {\n        const path = samples[0].path;\n\n        let previous = savedValue?.location || '';\n\n        if (!previous && this.configRepository.getEnv().storage.mediaLocation) {\n          previous = current;\n        }\n\n        if (!previous) {\n          previous = path.startsWith('upload/') ? 'upload' : '/usr/src/app/upload';\n        }\n\n        if (previous !== current) {\n          this.logger.log(`Media location changed (from=${previous}, to=${current})`);\n\n          if (!path.startsWith(previous)) {\n            throw new Error(ErrorMessages.InconsistentMediaLocation);\n          }\n\n          this.logger.warn(\n            `Detected a change to media location, performing an automatic migration of file paths from ${previous} to ${current}, this may take awhile`,\n          );\n          await this.databaseRepository.migrateFilePaths(previous, current);\n        }\n      }\n\n      // Only set MediaLocation in systemMetadataRepository if needed\n      if (savedValue?.location !== current) {\n        await this.systemMetadataRepository.set(SystemMetadataKey.MediaLocation, { location: current });\n      }\n    });\n  }\n\n  @OnJob({ name: JobName.FileDelete, queue: QueueName.BackgroundTask })\n  async handleDeleteFiles(job: JobOf<JobName.FileDelete>): Promise<JobStatus> {","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/storage.service.ts#L100-L136","documentation":"On startup (onBootstrap), Immich compares the stored previous media location with the current one; if they differ and the new external path is not a subpath of the previous one, it throws rather than attempting a migration, because an automatic path migration would be unsafe.","triggerScenarios":"Changing the upload/data volume mount so the new external path is not nested under the old path (e.g. from /usr/src/app/upload to /mnt/library), then starting the server.","commonSituations":"Docker compose volume changes; moving from a bind mount to a different host directory; renaming the host folder; container image changes that relocate the internal upload path.","solutions":["Restore the original mount path so data sits where Immich expects it, or make the new location a subdirectory of the old path so a migration is possible.","If the move is intentional and paths aren't nested, follow the docs at https://docs.immich.app/errors#inconsistent-media-location to manually update stored paths or restore the database/volume consistently.","Ensure database and uploaded files were moved together; a mismatch between DB paths and filesystem is the root cause.","Use immich's provided migration tooling (migrate file paths) only when the new path starts with the old one."],"exampleFix":"// before (docker-compose.yml)\nvolumes:\n  - /mnt/newlibrary:/usr/src/app/upload\n// after\nvolumes:\n  - /mnt/newlibrary/upload:/usr/src/app/upload  # keeps external location consistent or nested under previous path","handlingStrategy":"try-catch","validationCode":"// before startup, verify the configured media path is consistent with the database's stored location\nconst previous = await db.getSystemMetadataMediaLocation();\nif (previous && !mediaPath.startsWith(previous)) throw new Error('Media location change is not a subpath; manual migration required');","typeGuard":null,"tryCatchPattern":"try {\n  await startImmichServer();\n} catch (e) {\n  if (/inconsistent media location/i.test(String(e.message))) {\n    // restore original mount path or follow docs.immich.app/errors#inconsistent-media-location\n    process.exit(1);\n  } else throw e;\n}","preventionTips":["Keep the host-side mount path for the upload volume stable across deployments","Move database and files together when relocating data","If the path must change, make the new path a subpath of the old one so auto-migration works","Consult docs.immich.app/errors#inconsistent-media-location before changing volumes"],"tags":["immich","storage","startup","paths","docker"],"backgroundTag":"inconsistent-media-location","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"}