{"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/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/services/storage.service.ts#L100-L136","documentation":"StorageService tracks the configured media location in system metadata. On startup it compares the persisted 'previous' location with the 'current' resolved media path. If they differ AND existing repository file paths do NOT start with the previous location, it throws ErrorMessages.InconsistentMediaLocation (storage.service.ts:118, a plain Error). This protects against silently relocating media that lives in an unexpected place.","triggerScenarios":"Booting the server after the upload/media directory was moved or the storageVolume mount changed, while existing DB file paths were not migrated to match — i.e. previous != current and at least one stored path does not begin with the previous prefix.","commonSituations":"Changing the upload volume / external library path between deploys, restoring a DB backup against a different media mount, Docker volume remapping, or moving the library folder by hand instead of via the migration tool.","solutions":["Follow the docs link in the message (https://docs.immich.app/errors#inconsistent-media-location) and run the official storage-location migration procedure.","Restore the previous media path/mount so previous == current, then reboot.","If paths are genuinely relocated, migrate file paths first (databaseRepository.migrateFilePaths) so they start with the current prefix, then restart.","Avoid moving the upload directory by hand; use the supported migration flow."],"exampleFix":"// before - manually moved media, DB paths stale\n// mv /media/photos /mnt/new/photos  -> then boot -> error\n// after - migrate via supported flow, then boot\n// 1. keep/match the previous mount, OR run the official path migration,\n// 2. confirm stored paths start with the configured media location, then restart the server.","handlingStrategy":"try-catch","validationCode":"// Pre-flight: ensure configured media location matches persisted location\n// before booting the app against a moved volume.\nconst persisted = await systemMetadataApi.get(SystemMetadataKey.MediaLocation);\nconst current = resolveMediaLocation(); // your deployment's media path\nif (persisted && persisted.location !== current) {\n  // Do NOT just boot — run the official migration first.\n  throw new Error(`Media location mismatch (was ${persisted.location}, now ${current}). Run the migration.`);\n}","typeGuard":"const isInconsistentMediaLocation = (e: unknown): boolean =>\n  e instanceof Error && /inconsistent media location/i.test(e.message);","tryCatchPattern":"try {\n  await bootstrapServer();\n} catch (e) {\n  if (/inconsistent media location/i.test(String((e as Error).message))) {\n    // halt boot; surface the docs link and require operator action\n    failDeployment('Inconsistent media location detected. See https://docs.immich.app/errors#inconsistent-media-location and run the storage migration before restarting.');\n  } else throw e;\n}","preventionTips":["Never move the upload/media directory by hand; use the supported migration flow.","After volume/mount changes, verify stored file paths still start with the configured location before boot.","Keep the SystemMetadata MediaLocation record consistent with the actual mount."],"tags":["storage","media-location","migration","filesystem"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}