What causes "${modelRole} in inference.yml must define model_name." in PaddlePaddle/PaddleOCR?

Open the model's inference.yml and add the correct model_name for the role (matching what you pass as *_model_name).

${modelRole} in inference.yml must define model_name.

Error message

${modelRole} in inference.yml must define model_name.

What it means

After downloading a model package, the library parses its inference.yml and extracts the model_name field via extractInferenceModelName(). If the yml exists but contains no model_name for the role being validated, the package cannot be identified, so validateLoadedModelName() throws. This guards against corrupted, hand-edited, or non-standard model directories.

Source

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

  return Object.fromEntries(
    OCR_MODEL_ROLES.map((role) => [
      role.selectionKey,
      getSelectedModelName(baseSelection, configSelection, explicitSelection, role.selectionKey)
    ])
  ) as unknown as PipelineModelSelection;
}

export function validateLoadedModelName(
  modelRole: string,
  expectedModelName: string | null | undefined,
  configText: string
): void {
  if (!expectedModelName) {
    throw new Error(`${modelRole} model selection must define model_name.`);
  }
  const declaredModelName = extractInferenceModelName(configText);
  if (!declaredModelName) {
    throw new Error(`${modelRole} in inference.yml must define model_name.`);
  }
  if (declaredModelName !== expectedModelName) {
    throw new Error(
      `${modelRole} in inference.yml declares model_name "${declaredModelName}" but requested model_name is "${expectedModelName}".`
    );
  }
}

function resolveSelectedAsset(
  assetRole: string,
  modelRole: string,
  selectionKey: keyof PipelineModelSelection,
  baseSelection: PipelineModelSelection | null,
  configSelection: PipelineModelSelection | null,
  explicitSelection: Record<string, string | null> | null,
  configAssets: Partial<Record<string, ModelAsset>> | null,
  explicitAssets: Record<string, ModelAsset> | null
): ModelAsset | null {

View on GitHub (pinned to 2661c7c0ef)

Solutions

Open the model's inference.yml and add the correct model_name for the role (matching what you pass as *_model_name).
Re-download or re-export the model package to rule out corruption.
Use an official prebuilt model package, which always declares model_name.

Example fix

# before (models/det/inference.yml)
HyperParameters: {}

# after
HyperParameters:
  model_name: PP-OCRv5_mobile_det

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check a self-hosted model package before passing its dir
async function modelPackageDeclaresName(dir: string): Promise<boolean> {
  const yml = await (await fetch(`${dir}/inference.yml`)).text();
  return /model_name\s*:\s*\S/.test(yml);
}

Try / catch

try {
  const ocr = await PaddleOCR.create(opts);
  await ocr.initialize();
} catch (e) {
  if (e instanceof Error && e.message.includes('inference.yml must define model_name')) {
    // your model package is malformed: fix the yml inside the model dir
    throw new Error('Model package invalid: add model_name to its inference.yml', { cause: e });
  }
  throw e;
}

Prevention

When self-hosting converted models, verify inference.yml contains model_name in CI.
Use official model archives unless you control the packaging pipeline.

When it happens

Trigger: Pointing *_model_dir at a self-packaged model whose inference.yml omits model_name; a partially downloaded or truncated model package; a repackaged PaddleOCR model converted incorrectly.

Common situations: Self-hosting converted/exported models; CI caches that truncated the model download; mixing models from a different PaddleOCR toolchain version with a different yml schema.

Related errors

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