immich-app/immich · error · Error

Target media location must be an absolute path

Error message

Target media location must be an absolute path

What it means

Thrown (plain Error) by CliService during the storage-location migration flow. After stripping a leading './' from the old value, it requires the new value to be absolute; node's path.isAbsolute must return true. This prevents migrations from writing to a relative (and thus unpredictable) target.

Source

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

  }

  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 199723261c)

Solutions

1. Provide an absolute target path, e.g. '/mnt/immich/library' or '/usr/src/app/upload'.
2. Resolve the path with path.resolve() before passing it so './x' becomes absolute.
3. Verify the target directory exists and is writable by the server process.

Example fix

// before
await cliService['migrateFilePaths']({ oldValue: './upload', newValue: 'photos', confirm });

// after
const { isAbsolute, resolve } = require('path');
let target = newValue;
if (!isAbsolute(target)) target = resolve(target);
// target === process.cwd() + '/photos'
await cliService['migrateFilePaths']({ oldValue: './upload', newValue: target, confirm });

const { isAbsolute, resolve } = require('path');
const target = isAbsolute(newValue) ? newValue : resolve(newValue);
if (!isAbsolute(target)) throw new Error('Target media location must be absolute');

function isAbsolutePath(p: string): boolean {
  const { isAbsolute } = require('path');
  return isAbsolute(p);
}

When it happens

Trigger: Invoking the CLI storage-path migration with a newValue that is a relative path (e.g. './photos' or 'photos') rather than a rooted path like '/mnt/photos'.

Common situations: Docker/relative-path configs; copying a path from a config that used './' notation; misconfigured volume mount path passed verbatim.

Related errors

• Detected an inconsistent media location. For more informatio
• Failed to read: "${externalPath} (${internalPath}) - ${docsM
• Failed to create "${externalPath} - ${docsMessage}"
• Failed to write "${externalPath} - ${docsMessage}"
• Failed to read helmet file: ${helmetFile}

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/abef5c45b7da2619. Report an issue: GitHub.