{"record":{"id":"74778f8facbfcbf4","repo":"PaddlePaddle/PaddleOCR","slug":"modelrole-in-inference-yml-declares-model-name","errorCode":null,"errorMessage":"${modelRole} in inference.yml declares model_name \"${declaredModelName}\" but requested model_name is \"${expectedModelName}\".","messagePattern":"(.+?) in inference\\.yml declares model_name \"(.+?)\" but requested model_name is \"(.+?)\"\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"paddleocr-js/packages/core/src/pipelines/ocr/shared.ts","lineNumber":406,"sourceCode":"      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 {\n  const explicitAsset = explicitAssets?.[assetRole];\n  if (explicitAsset) {\n    return explicitAsset;","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr-js/packages/core/src/pipelines/ocr/shared.ts#L388-L424","documentation":"validateLoadedModelName() compares the model_name declared inside the loaded model's inference.yml with the model_name the user requested. A mismatch means the directory/URL you supplied actually contains a different model than you asked for — loading it would run the wrong weights under the wrong name, so it is a hard error.","triggerScenarios":"Setting text_detection_model_name: 'PP-OCRv5_mobile_det' but text_detection_model_dir pointing at a directory containing PP-OCRv5_server_det (or any other model); reusing a cached model path after switching model names in code.","commonSituations":"Renaming the requested model but forgetting to update the model_dir; two models extracted into overlapping cache directories; copy-pasting a det model path for a rec model.","solutions":["Make the requested *_model_name match the model_name declared in the target directory's inference.yml (the error prints both values).","Update the *_model_dir to point at the directory that actually contains the requested model.","Clear stale model caches if a shared cache directory mixes versions."],"exampleFix":"// before\nconst ocr = await PaddleOCR.create({\n  textRecognitionModelName: 'PP-OCRv5_mobile_rec',\n  textRecognitionModelDir: '/models/server_rec/' // contains PP-OCRv5_server_rec\n});\n\n// after\nconst ocr = await PaddleOCR.create({\n  textRecognitionModelName: 'PP-OCRv5_server_rec',\n  textRecognitionModelDir: '/models/server_rec/'\n});","handlingStrategy":"validation","validationCode":"// Assert the yml in your model dir matches the name you request\nasync function assertModelDirMatches(dir: string, expectedName: string): Promise<void> {\n  const yml = await (await fetch(`${dir}/inference.yml`)).text();\n  const m = yml.match(/model_name\\s*:\\s*(\\S+)/);\n  if (!m || m[1] !== expectedName) {\n    throw new Error(`model dir '${dir}' contains '${m?.[1] ?? 'no model_name'}', expected '${expectedName}'`);\n  }\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('declares model_name')) {\n    // e.message shows both names: align textXModelName with the package contents\n  }\n  throw e;\n}","preventionTips":["Derive the model_name option by parsing the target package's inference.yml instead of hardcoding.","Keep one directory per model; never overwrite a cached model dir with different weights."],"tags":["model-selection","model-files","configuration","mismatch"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}