immich-app/immich · error

Target media location must be an absolute path

Error message

Target media location must be an absolute path

What it means

During a media-location migration, `migrateFilePaths` validates that the new target folder is an absolute path using isAbsolute(). Relative paths like './photos' or 'photos' are rejected with this Error because the migration must rewrite external-library asset paths to unambiguous locations.

Solutions

1. Provide the target as a fully qualified path, e.g. /usr/src/app/external/mount/photos or /mnt/photos.
2. Resolve the intended directory first (realpath/readlink -f) and paste the absolute result.
3. Make sure the path matches what the Immich container sees (container-internal absolute path, not host path).

Example fix

// before
const targetFolder = './photos';            // throws: Target media location must be an absolute path
// after
const targetFolder = '/usr/src/app/external/photos';

import { isAbsolute, resolve } from 'path';
// Validate the target folder before starting the migration
if (!isAbsolute(targetFolder)) {
  targetFolder = resolve(process.cwd(), targetFolder); // or prompt again
}

When it happens

Trigger: Answering the migration prompt (or supplying an EXTERNAL_HOST/ media location value) with a relative path such as './mnt/photos' or 'photos'; the source './' prefix is stripped but the target must still be absolute.

Common situations: Copy-pasting a relative Docker volume path; forgetting a leading slash; running the command on a host where the intended mount is only valid relative to a working directory.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• model_path must point to an existing file!
• Admin account does not exist
• Asset dimensions are not available for editing
• assetIds, albumId, or userId is required
• At least two people are required for merging

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

Appendix: source

Thrown at server/src/services/cli.service.ts:218

  }

  async migrateFilePaths({
    oldValue,
    newValue,
    confirm,
  }: {
    oldValue: string;
    newValue: string;
    confirm: (data: { sourceFolder: string; targetFolder: string }) => Promise<boolean>;
  }): Promise<boolean> {
    let sourceFolder = oldValue;
    if (sourceFolder.startsWith('./')) {
      sourceFolder = sourceFolder.slice(2);
    }

    const targetFolder = newValue;
    if (!isAbsolute(targetFolder)) {
      throw new Error('Target media location must be an absolute path');
    }

    if (!(await confirm({ sourceFolder, targetFolder }))) {
      return false;
    }

    await this.databaseRepository.migrateFilePaths(sourceFolder, targetFolder);

    return true;
  }

  cleanup() {
    return this.databaseRepository.shutdown();
  }
}

View on GitHub (pinned to e55ac299a4)