{"record":{"id":"7f56f8c0628f7027","repo":"PaddlePaddle/PaddleOCR","slug":"modelrole-in-inference-yml-must-define-model-na","errorCode":null,"errorMessage":"${modelRole} in inference.yml must define model_name.","messagePattern":"(.+?) in inference\\.yml must define model_name\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"paddleocr-js/packages/core/src/pipelines/ocr/shared.ts","lineNumber":403,"sourceCode":"  return Object.fromEntries(\n    OCR_MODEL_ROLES.map((role) => [\n      role.selectionKey,\n      getSelectedModelName(baseSelection, configSelection, explicitSelection, role.selectionKey)\n    ])\n  ) as unknown as PipelineModelSelection;\n}\n\nexport function validateLoadedModelName(\n  modelRole: string,\n  expectedModelName: string | null | undefined,\n  configText: string\n): void {\n  if (!expectedModelName) {\n    throw new Error(`${modelRole} model selection must define model_name.`);\n  }\n  const declaredModelName = extractInferenceModelName(configText);\n  if (!declaredModelName) {\n    throw new Error(`${modelRole} in inference.yml must define model_name.`);\n  }\n  if (declaredModelName !== expectedModelName) {\n    throw new Error(\n      `${modelRole} in inference.yml declares model_name \"${declaredModelName}\" but requested model_name is \"${expectedModelName}\".`\n    );\n  }\n}\n\nfunction resolveSelectedAsset(\n  assetRole: string,\n  modelRole: string,\n  selectionKey: keyof PipelineModelSelection,\n  baseSelection: PipelineModelSelection | null,\n  configSelection: PipelineModelSelection | null,\n  explicitSelection: Record<string, string | null> | null,\n  configAssets: Partial<Record<string, ModelAsset>> | null,\n  explicitAssets: Record<string, ModelAsset> | null\n): ModelAsset | null {","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr-js/packages/core/src/pipelines/ocr/shared.ts#L385-L421","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before (models/det/inference.yml)\nHyperParameters: {}\n\n# after\nHyperParameters:\n  model_name: PP-OCRv5_mobile_det","handlingStrategy":"try-catch","validationCode":"// Pre-check a self-hosted model package before passing its dir\nasync function modelPackageDeclaresName(dir: string): Promise<boolean> {\n  const yml = await (await fetch(`${dir}/inference.yml`)).text();\n  return /model_name\\s*:\\s*\\S/.test(yml);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const ocr = await PaddleOCR.create(opts);\n  await ocr.initialize();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('inference.yml must define model_name')) {\n    // your model package is malformed: fix the yml inside the model dir\n    throw new Error('Model package invalid: add model_name to its inference.yml', { cause: e });\n  }\n  throw e;\n}","preventionTips":["When self-hosting converted models, verify inference.yml contains model_name in CI.","Use official model archives unless you control the packaging pipeline."],"tags":["model-selection","model-files","inference-yml"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}