immich-app/immich · error · Error

Media location is not set.

Error message

Media location is not set.

What it means

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.

Solutions

1. Ensure StorageCore.setMediaLocation(location) is called during server bootstrap before any code reads the media location.
2. Verify the storage config / IMMICH_MEDIA_LOCATION environment variable is set so initialization produces a real location.
3. In tests, call StorageCore.setMediaLocation('/tmp/test-media') in a beforeAll hook (and reset() in afterAll).
4. Check call ordering: nothing should call getMediaLocation() from module top-level code that runs before initialization.

Example fix

// before
const service = new MyService(storageRepo);
const dir = StorageCore.getMediaLocation(); // Error: Media location is not set.
// after
StorageCore.setMediaLocation(process.env.IMMICH_MEDIA_LOCATION ?? './upload');
const dir = StorageCore.getMediaLocation();
const service = new MyService(storageRepo);

if (typeof process.env.IMMICH_MEDIA_LOCATION !== 'string') {
  throw new Error('IMMICH_MEDIA_LOCATION must be set before using StorageCore');
}

function isMediaLocationReady(): boolean {
  try { StorageCore.getMediaLocation(); return true; } catch { return false; }
}

let mediaDir: string;
try {
  mediaDir = StorageCore.getMediaLocation();
} catch (e) {
  if (e instanceof Error && e.message === 'Media location is not set.') {
    StorageCore.setMediaLocation(process.env.IMMICH_MEDIA_LOCATION ?? './upload');
    mediaDir = StorageCore.getMediaLocation();
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Album must have an owner
• Cannot remove the last album owner
• Detected an inconsistent media location. For more…
• Failed to create
• Failed to read: " ( )

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/13553700be0af020. Report an issue: GitHub.

Appendix: source

Thrown at server/src/cores/storage.core.ts:98

        cryptoRepository,
        moveRepository,
        personRepository,
        storageRepository,
        systemMetadataRepository,
        logger,
      );
    }

    return instance;
  }

  static reset() {
    instance = null;
  }

  static getMediaLocation(): string {
    if (mediaLocation === undefined) {
      throw new Error('Media location is not set.');
    }

    return mediaLocation;
  }

  static setMediaLocation(location: string) {
    mediaLocation = location;
  }

  static getFolderLocation(folder: StorageFolder, userId: string) {
    return join(StorageCore.getBaseFolder(folder), userId);
  }

  static getLibraryFolder(user: { storageLabel: string | null; id: string }) {
    return join(StorageCore.getBaseFolder(StorageFolder.Library), user.storageLabel || user.id);
  }

  static getBaseFolder(folder: StorageFolder) {

View on GitHub (pinned to e55ac299a4)