PaddlePaddle/PaddleOCR · error

${modelRole} model selection must define model_name.

Error message

${modelRole} model selection must define model_name.

What it means

validateLoadedModelName() is called after a model config (inference.yml) has been loaded to cross-check the declared model_name against what the user requested. If the caller-side expected model name is null/undefined at that point, there is nothing to validate against, which indicates the resolved model selection never defined model_name — a programming/config error, so it throws immediately.

Source

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

  baseSelection: PipelineModelSelection | null,
  configSelection: PipelineModelSelection | null,
  explicitSelection: Record<string, string | null> | null
): PipelineModelSelection {
  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,

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Always pair model_dir/asset options with the matching model_name option (e.g. text_detection_model_dir + text_detection_model_name).
2. If authoring pipelineConfig by hand, ensure each model selection entry includes model_name.
3. Prefer the high-level options (lang / ocrVersion) so names are filled from the default selection.

Example fix

// before
const ocr = await PaddleOCR.create({
  textDetectionModelDir: '/models/det/'
});

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

// Ensure every model_dir option is paired with its model_name before create()
function validateModelPairs(o: Record<string, unknown>): string[] {
  const pairs: [string, string][] = [
    ['textDetectionModelDir', 'textDetectionModelName'],
    ['textRecognitionModelDir', 'textRecognitionModelName']
  ];
  return pairs.filter(([dir, name]) => o[dir] !== undefined && o[name] === undefined).map(([d]) => d);
}

function hasCompleteModelSelection(o: Record<string, unknown>): boolean {
  const detName = o.textDetectionModelName ?? o.text_detection_model_name;
  const recName = o.textRecognitionModelName ?? o.text_recognition_model_name;
  const detDir = o.textDetectionModelDir ?? o.text_detection_model_dir;
  const recDir = o.textRecognitionModelDir ?? o.text_recognition_model_dir;
  return (detDir === undefined || detName !== undefined) && (recDir === undefined || recName !== undefined);
}

try {
  const ocr = await PaddleOCR.create(opts);
} catch (e) {
  if (e instanceof Error && e.message.endsWith('must define model_name.')) {
    throw new ConfigError('Model dirs require matching model names', { cause: e });
  }
  throw e;
}

When it happens

Trigger: A pipeline code path that loads a model asset by directory/URL without a resolved model_name reaching validation, e.g. an explicit asset (model_dir) supplied without its companion *_model_name, or a custom pipelineConfig whose selection object lacks model_name.

Common situations: Supplying only *_model_dir options and forgetting *_model_name; hand-writing a pipelineConfig model selection block and omitting the model_name field.

Related errors

• OCR model selection must define both detection and recogniti
• worker mode does not support a custom fetch implementation.
• Conflicting values provided for ${label}: ${aliases.join(",
• Unknown model asset "${modelName}".
• ${modelRole} in inference.yml declares model_name "${declare

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