immich-app/immich · error · Error

Unknown CLIP model: ${modelName}

Error message

Unknown CLIP model: ${modelName}

What it means

Thrown by getCLIPModelInfo (server/src/utils/misc.ts) when the (cleaned) CLIP model name is not present in CLIP_MODEL_INFO (constants.ts), the registry that maps model names to their embedding dimSize. cleanModelName takes the last '/'-segment and replaces ':' with '_'. An unknown model means Immich cannot determine the vector dimensionality for smart search / duplicate detection.

Source

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

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;
  }

  const result: Partial<T> = {};
  const keys = Object.keys(target).toSorted() as Array<keyof T>;
  for (const key of keys) {
    result[key] = sortKeys(target[key]);
  }
  return result as T;
}

View on GitHub (pinned to 199723261c)

Solutions

1. Set machineLearning.clip.modelName to one of the keys in CLIP_MODEL_INFO (constants.ts) — e.g. 'ViT-B-32__openai', 'XLM-Roberta-Large-Vit-L-14', 'ViT-H-14__laion2b-s32b-b79k'.
2. Upgrade Immich to a version that registers the model you want to use.
3. Re-run the smart-search job after correcting the model name.

Example fix

// before
machineLearning.clip.modelName = 'some-custom-clip-v2';

// after
machineLearning.clip.modelName = 'ViT-B-32__openai';

import { CLIP_MODEL_INFO } from 'src/constants';
const name = cleanModelName(config.machineLearning.clip.modelName);
if (!(name in CLIP_MODEL_INFO)) { /* pick a default registered model */ }

const isRegisteredClipModel = (modelName: string): boolean =>
  Object.prototype.hasOwnProperty.call(CLIP_MODEL_INFO, cleanModelName(modelName));

try { getCLIPModelInfo(modelName); }
catch (e) { if (/Unknown CLIP model/.test(e.message)) { modelName = 'ViT-B-32__openai'; /* retry */ } else throw e; }

When it happens

Trigger: Machine-learning smart search or duplicate detection runs while machineLearning.clip.modelName is set to a CLIP model not in the CLIP_MODEL_INFO registry.

Common situations: User configures a custom/unsupported CLIP model name; model name typo or wrong casing; new model not yet supported by the installed Immich version; copied model name from a newer Immich release onto an older server.

Related errors

• Smart search is not enabled
• Unknown CLIP model: ${newConfig.machineLearning.clip.modelNa
• Invalid CLIP dimension size: ${dimSize}
• Machine learning request '${JSON.stringify(config)}' failed
• Asset ${dto.queryAssetId} has no embedding

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