{"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":155,"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":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/utils/misc.ts#L137-L173","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Choose a supported CLIP model from the immich docs (e.g. 'Xenova/clip-vit-base-patch-32' or 'immich-app/immichclip...').","If a custom model is required, verify it is supported by your immich-machine-learning version or downgrade/upgrade ML image accordingly.","Reset the machine-learning smart-search model setting to its default value.","When self-extending, add the model with its dimSize to CLIP_MODEL_INFO before using it."],"exampleFix":"// before\n\"machineLearning.clip.modelName\": \"my-custom-clip\"\n// after\n\"machineLearning.clip.modelName\": \"Xenova/clip-vit-base-patch-32\"","handlingStrategy":"validation","validationCode":"const SUPPORTED = Object.keys(CLIP_MODEL_INFO);\nconst normalized = modelName.split('/').at(-1).replaceAll(':', '_');\nif (!SUPPORTED.includes(normalized)) throw new ConfigError(`Unsupported CLIP model: ${modelName}`);","typeGuard":"const isKnownClipModel = (m: string): boolean => m.split('/').at(-1)?.replaceAll(':', '_') in CLIP_MODEL_INFO;","tryCatchPattern":"try { info = getCLIPModelInfo(model); } catch (e) { if (e.message.startsWith('Unknown CLIP model')) { model = DEFAULT_CLIP_MODEL; } else throw e; }","preventionTips":["Only select models listed in the immich documentation","Pin your ML image version to one matching your configured models","After upgrades, verify configured models still appear in CLIP_MODEL_INFO"],"tags":["machine-learning","clip","configuration","unsupported-model"],"backgroundTag":"resource-not-found","analyzedSha":"e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}