{"record":{"id":"304d2c0f91296368","repo":"immich-app/immich","slug":"unknown-clip-model-modelname","errorCode":null,"errorMessage":"Unknown CLIP model: ${modelName}","messagePattern":"Unknown CLIP model: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/src/utils/misc.ts","lineNumber":158,"sourceCode":"export interface OpenGraphTags {\n  title: string;\n  description: string;\n  imageUrl?: string;\n}\n\nfunction cleanModelName(modelName: string): string {\n  const token = modelName.split('/').at(-1);\n  if (!token) {\n    throw new Error(`Invalid model name: ${modelName}`);\n  }\n\n  return token.replaceAll(':', '_');\n}\n\nexport function getCLIPModelInfo(modelName: string) {\n  const modelInfo = CLIP_MODEL_INFO[cleanModelName(modelName)];\n  if (!modelInfo) {\n    throw new Error(`Unknown CLIP model: ${modelName}`);\n  }\n\n  return modelInfo;\n}\n\nfunction sortKeys<T>(target: T): T {\n  if (!target || typeof target !== 'object' || Array.isArray(target)) {\n    return target;\n  }\n\n  const result: Partial<T> = {};\n  const keys = Object.keys(target).toSorted() as Array<keyof T>;\n  for (const key of keys) {\n    result[key] = sortKeys(target[key]);\n  }\n  return result as T;\n}\n","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/server/src/utils/misc.ts#L140-L176","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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'.","Upgrade Immich to a version that registers the model you want to use.","Re-run the smart-search job after correcting the model name."],"exampleFix":"// before\nmachineLearning.clip.modelName = 'some-custom-clip-v2';\n\n// after\nmachineLearning.clip.modelName = 'ViT-B-32__openai';","handlingStrategy":"validation","validationCode":"import { CLIP_MODEL_INFO } from 'src/constants';\nconst name = cleanModelName(config.machineLearning.clip.modelName);\nif (!(name in CLIP_MODEL_INFO)) { /* pick a default registered model */ }","typeGuard":"const isRegisteredClipModel = (modelName: string): boolean =>\n  Object.prototype.hasOwnProperty.call(CLIP_MODEL_INFO, cleanModelName(modelName));","tryCatchPattern":"try { getCLIPModelInfo(modelName); }\ncatch (e) { if (/Unknown CLIP model/.test(e.message)) { modelName = 'ViT-B-32__openai'; /* retry */ } else throw e; }","preventionTips":["Restrict the model picker UI to keys present in CLIP_MODEL_INFO.","After upgrades, re-validate that the configured CLIP model is still registered."],"tags":["machine-learning","clip","smart-search","config","model-registry"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}