What causes "Invalid model name: ${modelName}" in immich-app/immich?

Set a full, valid model name in the ML settings (e.g. 'Xenova/clip-vit-base-patch-32' or 'img-clip-large-params-v1').

immich-app/immich · error · Error

Invalid model name

Error message

Invalid model name: ${modelName}

What it means

cleanModelName() takes an ML model identifier (e.g. 'Xenova/clip-vit-base-patch-32'), splits on '/', and uses the last path segment. If the string has no usable final segment (empty string or malformed), it throws because the model name cannot be normalized for lookup or local storage.

Solutions

Set a full, valid model name in the ML settings (e.g. 'Xenova/clip-vit-base-patch-32' or 'img-clip-large-params-v1').
Ensure the value is non-empty and does not end with '/' before saving machine-learning configuration.
Reset ML settings to defaults if a bad value was persisted in the config DB.
Use one of the supported model names listed in the documentation so getCLIPModelInfo can resolve it.

Example fix

// before
machineLearning.clip.modelName = '';
// after
machineLearning.clip.modelName = 'Xenova/clip-vit-base-patch-32';

Defensive patterns

Strategy: validation

Validate before calling

function isValidModelName(name) {
  return typeof name === 'string' && name.length > 0 && !name.endsWith('/') && name.split('/').at(-1).length > 0;
}

Try / catch

try { info = getCLIPModelInfo(modelName); } catch (e) { if (e.message.startsWith('Invalid model name')) { modelName = DEFAULT_CLIP_MODEL; info = getCLIPModelInfo(modelName); } else throw e; }

Prevention

Validate model-name settings at input time (non-empty, no trailing slash)
Never persist empty ML model fields
Use dropdowns of supported models instead of free-text where possible

When it happens

Trigger: Calling modelInfo/cleanModelName with an empty string, a string ending in '/', or otherwise lacking a non-empty segment after the last '/'.

Common situations: Machine-learning settings saved with an empty model name; config migration leaving blank model fields; programmatic config edits passing 'org/' instead of 'org/model'.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at server/src/utils/misc.ts:146

      batch = [];
    }
  }

  if (batch.length > 0) {
    yield batch;
  }
}

export interface OpenGraphTags {
  title: string;
  description: string;
  imageUrl?: string;
}

function cleanModelName(modelName: string): string {
  const token = modelName.split('/').at(-1);
  if (!token) {
    throw new Error(`Invalid model name: ${modelName}`);
  }

  return token.replaceAll(':', '_');
}

export function getCLIPModelInfo(modelName: string) {
  const modelInfo = CLIP_MODEL_INFO[cleanModelName(modelName)];
  if (!modelInfo) {
    throw new Error(`Unknown CLIP model: ${modelName}`);
  }

  return modelInfo;
}

function sortKeys<T>(target: T): T {
  if (!target || typeof target !== 'object' || Array.isArray(target)) {
    return target;
  }

View on GitHub (pinned to e55ac299a4)