{"record":{"id":"13553700be0af020","repo":"immich-app/immich","slug":"media-location-is-not-set","errorCode":null,"errorMessage":"Media location is not set.","messagePattern":"Media location is not set\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/src/cores/storage.core.ts","lineNumber":98,"sourceCode":"        cryptoRepository,\n        moveRepository,\n        personRepository,\n        storageRepository,\n        systemMetadataRepository,\n        logger,\n      );\n    }\n\n    return instance;\n  }\n\n  static reset() {\n    instance = null;\n  }\n\n  static getMediaLocation(): string {\n    if (mediaLocation === undefined) {\n      throw new Error('Media location is not set.');\n    }\n\n    return mediaLocation;\n  }\n\n  static setMediaLocation(location: string) {\n    mediaLocation = location;\n  }\n\n  static getFolderLocation(folder: StorageFolder, userId: string) {\n    return join(StorageCore.getBaseFolder(folder), userId);\n  }\n\n  static getLibraryFolder(user: { storageLabel: string | null; id: string }) {\n    return join(StorageCore.getBaseFolder(StorageFolder.Library), user.storageLabel || user.id);\n  }\n\n  static getBaseFolder(folder: StorageFolder) {","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/cores/storage.core.ts#L80-L116","documentation":"StorageCore.getMediaLocation() returns the module-level mediaLocation string that must first be established via setMediaLocation() (typically during server bootstrap from the storage config/environment). If getMediaLocation() is called before initialization — or after StorageCore.reset() cleared it — mediaLocation is still undefined and this plain Error is thrown as an internal invariant violation.","triggerScenarios":"Any code path calling StorageCore.getMediaLocation() before StorageCore.setMediaLocation() ran during app bootstrap; code invoked during testing or module init before the storage core was configured; calling after StorageCore.reset() cleared the singleton.","commonSituations":"Unit tests instantiating services that depend on StorageCore without calling setMediaLocation first; custom bootstrap code skipping the storage initialization step; a missing or unset storage config / IMMICH_MEDIA_LOCATION env var so initialization never sets it.","solutions":["Ensure StorageCore.setMediaLocation(location) is called during server bootstrap before any code reads the media location.","Verify the storage config / IMMICH_MEDIA_LOCATION environment variable is set so initialization produces a real location.","In tests, call StorageCore.setMediaLocation('/tmp/test-media') in a beforeAll hook (and reset() in afterAll).","Check call ordering: nothing should call getMediaLocation() from module top-level code that runs before initialization."],"exampleFix":"// before\nconst service = new MyService(storageRepo);\nconst dir = StorageCore.getMediaLocation(); // Error: Media location is not set.\n// after\nStorageCore.setMediaLocation(process.env.IMMICH_MEDIA_LOCATION ?? './upload');\nconst dir = StorageCore.getMediaLocation();\nconst service = new MyService(storageRepo);","handlingStrategy":"try-catch","validationCode":"if (typeof process.env.IMMICH_MEDIA_LOCATION !== 'string') {\n  throw new Error('IMMICH_MEDIA_LOCATION must be set before using StorageCore');\n}","typeGuard":"function isMediaLocationReady(): boolean {\n  try { StorageCore.getMediaLocation(); return true; } catch { return false; }\n}","tryCatchPattern":"let mediaDir: string;\ntry {\n  mediaDir = StorageCore.getMediaLocation();\n} catch (e) {\n  if (e instanceof Error && e.message === 'Media location is not set.') {\n    StorageCore.setMediaLocation(process.env.IMMICH_MEDIA_LOCATION ?? './upload');\n    mediaDir = StorageCore.getMediaLocation();\n  } else throw e;\n}","preventionTips":["Always run setMediaLocation during app bootstrap before any storage-dependent code.","In tests, set and reset media location in global beforeAll/afterAll hooks.","Avoid top-level calls to getMediaLocation that execute before initialization.","Keep the storage config / env var present in every deployment environment."],"tags":["initialization","storage","invariant","bootstrap"],"backgroundTag":"missing-env-var","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"}