immich-app/immich · error · Error

Unknown CLIP model

Error message

Unknown CLIP model: ${modelName}

What it means

getCLIPModelInfo() looks up the normalized model name in the CLIP_MODEL_INFO table to obtain metadata (notably dimSize for the vector dimension). If the name is valid syntactically but not one of the supported/bundled CLIP models, it throws, preventing a mismatch between the configured model and the embedding dimension the vector database expects.

Solutions

1. Choose a supported CLIP model from the immich docs (e.g. 'Xenova/clip-vit-base-patch-32' or 'immich-app/immichclip...').
2. If a custom model is required, verify it is supported by your immich-machine-learning version or downgrade/upgrade ML image accordingly.
3. Reset the machine-learning smart-search model setting to its default value.
4. When self-extending, add the model with its dimSize to CLIP_MODEL_INFO before using it.

Example fix

// before
"machineLearning.clip.modelName": "my-custom-clip"
// after
"machineLearning.clip.modelName": "Xenova/clip-vit-base-patch-32"

const SUPPORTED = Object.keys(CLIP_MODEL_INFO);
const normalized = modelName.split('/').at(-1).replaceAll(':', '_');
if (!SUPPORTED.includes(normalized)) throw new ConfigError(`Unsupported CLIP model: ${modelName}`);

const isKnownClipModel = (m: string): boolean => m.split('/').at(-1)?.replaceAll(':', '_') in CLIP_MODEL_INFO;

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

When it happens

Trigger: Configuring CLIP to a custom model name not present in CLIP_MODEL_INFO (after passing cleanModelName), then triggering config validation (onConfigValidate) or a search-embedding request.

Common situations: Typing an unsupported Hugging Face model into the smart-search model setting; upgrading immich-machine-learning where an older community model was removed; expecting arbitrary CLIP models to work without a dimension entry.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Invalid CLIP dimension size
• Invalid model name
• Machine learning request
• Unknown CLIP model: . Please check the model name for typos…
• Asset has no embedding

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

Appendix: source

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

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 e55ac299a4)