immich-app/immich · error · Error

Unknown CLIP model: ${newConfig.machineLearning.clip.modelNa

Error message

Unknown CLIP model: ${newConfig.machineLearning.clip.modelName}. Please check the model name for typos and confirm this is a supported model.

What it means

SmartInfoService.onConfigValidate() runs during the ConfigValidate event. It calls getCLIPModelInfo(modelName) for the proposed machineLearning.clip.modelName; if that throws (model not in the known registry), the catch rethrows a descriptive Error (smart-info.service.ts:28). This blocks the config from being saved.

Source

Thrown at server/src/services/smart-info.service.ts:28

@Injectable()
export class SmartInfoService extends BaseService {
  @OnEvent({ name: 'ConfigInit', workers: [ImmichWorker.Microservices] })
  async onConfigInit({ newConfig }: ArgOf<'ConfigInit'>) {
    await this.init(newConfig);
  }

  @OnEvent({ name: 'ConfigUpdate', workers: [ImmichWorker.Microservices], server: true })
  async onConfigUpdate({ oldConfig, newConfig }: ArgOf<'ConfigUpdate'>) {
    await this.init(newConfig, oldConfig);
  }

  @OnEvent({ name: 'ConfigValidate' })
  onConfigValidate({ newConfig }: ArgOf<'ConfigValidate'>) {
    try {
      getCLIPModelInfo(newConfig.machineLearning.clip.modelName);
    } catch {
      throw new Error(
        `Unknown CLIP model: ${newConfig.machineLearning.clip.modelName}. Please check the model name for typos and confirm this is a supported model.`,
      );
    }
  }

  private async init(newConfig: SystemConfig, oldConfig?: SystemConfig) {
    if (!isSmartSearchEnabled(newConfig.machineLearning)) {
      return;
    }

    await this.databaseRepository.withLock(DatabaseLock.CLIPDimSize, async () => {
      const { dimSize } = getCLIPModelInfo(newConfig.machineLearning.clip.modelName);
      const dbDimSize = await this.databaseRepository.getDimensionSize('smart_search');
      this.logger.verbose(`Current database CLIP dimension size is ${dbDimSize}`);

      const modelChange =
        oldConfig && oldConfig.machineLearning.clip.modelName !== newConfig.machineLearning.clip.modelName;
      const isDimSizeChange = dbDimSize !== dimSize;

View on GitHub (pinned to 199723261c)

Solutions

1. Use a modelName from the officially supported CLIP model list for your Immich version.
2. Check for typos and exact casing against the model registry.
3. If using a custom model, register/mount it in the machine-learning service and confirm it appears in the model list before referencing it.
4. Ensure the machine-learning container is running a compatible version that knows the model.

Example fix

// before
{ machineLearning: { clip: { modelName: 'clip-ViT-B32-mutuy' } } }
// after
{ machineLearning: { clip: { modelName: 'clip-ViT-B-32-multilingual-v1' } } }

const SUPPORTED_CLIP_MODELS = await fetchSupportedClipModels(); // from config options
if (!SUPPORTED_CLIP_MODELS.includes(newConfig.machineLearning.clip.modelName)) {
  throw new Error('Unsupported CLIP model name. Check the supported list.');
}
await systemConfigApi.update(newConfig);

const isKnownClipModel = (name: string, known: string[]): name is (typeof known)[number] =>
  known.includes(name);

try {
  await systemConfigApi.update(newConfig);
} catch (e) {
  if (/Unknown CLIP model/i.test(String((e as Error).message))) {
    showConfigError('clip.modelName', 'Pick a supported CLIP model from the list.');
  } else throw e;
}

When it happens

Trigger: Saving system config (PUT /system-config) with a machineLearning.clip.modelName that is not among the supported/known CLIP models, including typos and case mismatches if the lookup is case-sensitive.

Common situations: Pointing clip.modelName at a custom or newly downloaded model not yet registered, misspelling a model name, upgrading Immich without updating the ML server/models, or mismatched model availability between server and machine-learning containers.

Related errors

• Invalid CLIP dimension size: ${dimSize}
• Unknown CLIP model: ${modelName}
• Machine learning request '${JSON.stringify(config)}' failed
• Invalid SMTP configuration
• Smart search is not enabled

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