PaddlePaddle/PaddleOCR · error

Unknown model asset "${modelName}".

Error message

Unknown model asset "${modelName}".

What it means

Model roles (detection, recognition, etc.) are resolved by looking the requested model_name up in the built-in DEFAULT_MODEL_ASSETS registry, which maps known model names to their hosted URLs. If the name is not a key in that registry, no download URL can be determined, so resolveModelAssetByName() throws rather than guessing a URL.

Source

Thrown at paddleocr-js/packages/core/src/pipelines/ocr/shared.ts:361

  if (value === "ignore" || value === "error") return value;
  return "warn";
}

function emitPipelineWarnings(warnings: string[], behavior: "warn" | "ignore" | "error"): void {
  if (!warnings.length || behavior === "ignore") return;
  if (behavior === "error") {
    throw new Error(warnings.join(" "));
  }
  for (const warning of warnings) {
    console.warn(`[PaddleOCR.js] ${warning}`);
  }
}

function resolveModelAssetByName(_modelRole: string, modelName: string): ModelAsset {
  const asset = DEFAULT_MODEL_ASSETS[modelName];
  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for missing Record key
  if (!asset) {
    throw new Error(`Unknown model asset "${modelName}".`);
  }
  return { url: asset.url };
}

function getSelectedModelName(
  baseSelection: PipelineModelSelection | null,
  configSelection: PipelineModelSelection | null,
  explicitSelection: Record<string, string | null> | null,
  selectionKey: keyof PipelineModelSelection
): string | null {
  return (
    explicitSelection?.[selectionKey] ??
    configSelection?.[selectionKey] ??
    baseSelection?.[selectionKey] ??
    null
  );
}

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Check the spelling and case of the model name against the library's exported model list / DEFAULT_MODEL_ASSETS keys.
2. Upgrade paddleocr-js to a version that ships the model you want.
3. If you host the model yourself, pass an explicit asset (e.g. text_detection_model_dir / a ModelAsset URL) together with the model name instead of relying on the default registry.

Example fix

// before
const ocr = await PaddleOCR.create({
  textDetectionModelName: 'PP-OCRv9_mobile_det'
});

// after
const ocr = await PaddleOCR.create({
  textDetectionModelName: 'PP-OCRv5_mobile_det'
});

// Validate model names against the names you know this version ships before create()
const KNOWN_MODELS = ['PP-OCRv5_mobile_det', 'PP-OCRv5_server_det', 'PP-OCRv5_mobile_rec', /* ... */];
function isKnownModel(name: string): boolean {
  return KNOWN_MODELS.includes(name);
}

function isValidModelName(name: unknown): name is string {
  return typeof name === 'string' && /^[PP-OCRv\d+_(mobile|server)(det|rec)]/i.test(name) !== undefined;
}

try {
  const ocr = await PaddleOCR.create(opts);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown model asset')) {
    // e.message contains the bad name; surface a config error to the user
    throw new ConfigError(`Unsupported model: ${e.message}`);
  }
  throw e;
}

When it happens

Trigger: Passing a model name that is not shipped with this version of the library, e.g. textDetectionModelName: 'PP-OCRv9_mobile_det' or a typo like 'pp-ocrv5_mobile_det' (lookup is exact and case-sensitive).

Common situations: Using a model name from newer upstream PaddleOCR docs than the installed paddleocr-js version supports; typos; assuming any HuggingFace model id works.

Related errors

• Unsupported lang/ocrVersion combination: lang="${lang}", ocr
• ${modelRole} model selection must define model_name.
• ${modelRole} in inference.yml declares model_name "${declare
• OCR model selection must define both detection and recogniti
• text_detection_model_dir requires text_detection_model_name.

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/7edb36c2ac3e97cc. Report an issue: GitHub.