PaddlePaddle/PaddleOCR · error · Error

Asset "${assetName}" references unknown model asset "${asset

Error message

Asset "${assetName}" references unknown model asset "${asset}".

What it means

Thrown by normalizeModelAsset() when an assets entry is a string shorthand (e.g. "pp-ocr-v4-det") that does not match any key in DEFAULT_MODEL_ASSETS. The library supports referencing built-in model bundles by name; an unrecognized name fails fast instead of silently producing an invalid URL. A typo or a version mismatch between the library and the name you use is the usual cause.

Source

Thrown at paddleocr-js/packages/core/src/resources/model-asset.ts:64

  bytes: number;
}

// --- Validation helpers ---

function isNonEmptyString(value: unknown): value is string {
  return typeof value === "string" && value.length > 0;
}

function isObject(value: unknown): value is Record<string, unknown> {
  return Boolean(value && typeof value === "object" && !Array.isArray(value));
}

export function normalizeModelAsset(assetName: string, asset: unknown): ModelAsset {
  if (isNonEmptyString(asset)) {
    const resolvedAsset = DEFAULT_MODEL_ASSETS[asset];
    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for missing Record key
    if (!resolvedAsset) {
      throw new Error(`Asset "${assetName}" references unknown model asset "${asset}".`);
    }
    return { url: resolvedAsset.url };
  }

  if (!isObject(asset)) {
    throw new Error(`Asset "${assetName}" must be an object.`);
  }
  if (!isNonEmptyString(asset.url)) {
    throw new Error(`Asset "${assetName}" must define url.`);
  }

  return {
    url: asset.url
  };
}

export function normalizeAssets(
  assets: Record<string, unknown> | undefined

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Check the DEFAULT_MODEL_ASSETS keys exported by your installed package version and use an exact name
2. Upgrade @paddleocr/core to the version whose built-in assets include the model you want
3. Replace the shorthand with an explicit object: { url: "https://.../model.tar" }

Example fix

// before
const ocr = await PaddleOCR.create({ assets: { det: "pp-ocr-v4-detect" } }); // typo: unknown asset

// after
const ocr = await PaddleOCR.create({
  assets: { det: { url: "https://your-host/paddle-ocr-v4-det.tar" } }
});

import { DEFAULT_MODEL_ASSETS } from "@paddleocr/core";
const isKnownPreset = (v: string): boolean =>
  Object.prototype.hasOwnProperty.call(DEFAULT_MODEL_ASSETS, v);

function isModelAssetPreset(value: unknown, registry: Record<string, unknown>): value is string {
  return typeof value === "string" && value in registry;
}

When it happens

Trigger: Passing { det: { modelPath: ... }, assets: { det: "pp-ocr-v5-det" } } where that key is not in DEFAULT_MODEL_ASSETS for the installed package version; copy-pasting a model name from newer docs into an older @paddleocr/core release.

Common situations: Upgrading docs/examples to a new model generation while the installed npm package is older; typos like "ppocr-v4-det"; custom names expected to work as aliases.

Related errors

• Asset "${assetName}" must be an object.
• Asset "${assetName}" must define url.
• Assets must define at least one asset.
• OCR pipeline config text must decode to an object.
• OCR pipeline config must be an object or YAML text.

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