PaddlePaddle/PaddleOCR · error

${modulePath}.model_name must be provided when ${modulePath}

Error message

${modulePath}.model_name must be provided when ${modulePath}.model_dir is set.

What it means

Thrown by validateModuleAsset() during config normalization: a module (e.g. SubModules.TextDetection) sets model_dir, but model_name is absent. model_name is required alongside model_dir so the resolved asset can be identified and registered; the combination model_dir-without-model_name is treated as an incomplete module definition.

Source

Thrown at paddleocr-js/packages/core/src/pipelines/ocr/config.ts:105

  if (!isPlainObject(input)) {
    throw new Error("OCR pipeline config must be an object or YAML text.");
  }
  return input;
}

function addFeatureWarning(warnings: string[], featureName: string, reason?: string): void {
  warnings.push(
    `${featureName} is not yet supported in PaddleOCR.js${reason ? `: ${reason}` : ""}.`
  );
}

function getModuleModelName(moduleConfig: YamlObject | null): string | null {
  return typeof moduleConfig?.model_name === "string" ? moduleConfig.model_name : null;
}

function validateModuleAsset(modulePath: string, modelName: string | null): void {
  if (!modelName) {
    throw new Error(
      `${modulePath}.model_name must be provided when ${modulePath}.model_dir is set.`
    );
  }
}

function getModuleAsset(
  assetName: string,
  modulePath: string,
  moduleConfig: YamlObject | null
): ModelAsset | null {
  if (moduleConfig?.model_dir == null) {
    return null;
  }
  if (isPlainObject(moduleConfig.model_dir)) {
    const asset = normalizeModelAsset(assetName, moduleConfig.model_dir);
    validateModuleAsset(modulePath, getModuleModelName(moduleConfig));
    return asset;
  }

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Add model_name next to model_dir in the offending module block (see the modulePath in the message)
2. Check the exact key spelling and that the value is a string
3. If you do not want to override the model, remove model_dir entirely and let defaults apply

Example fix

# before
SubModules:
  TextDetection:
    model_dir:
      url: "https://cdn/models/det.onnx"

# after
SubModules:
  TextDetection:
    model_name: PP-OCRv5_mobile_det
    model_dir:
      url: "https://cdn/models/det.onnx"

for (const [path, mod] of [["TextDetection", subModules.TextDetection], ["TextRecognition", subModules.TextRecognition]] as const) {
  if (mod?.model_dir != null && typeof mod.model_name !== "string") {
    throw new Error(`${path}.model_name is required when model_dir is set`);
  }
}

function isCompleteModule(mod: unknown): boolean {
  const m = mod as Record<string, unknown> | null;
  return m == null || m.model_dir == null || typeof m.model_name === "string";
}

When it happens

Trigger: A pipeline config with SubModules.TextDetection.model_dir set (as an asset descriptor) but no model_name key; model_name misspelled (model_Name, modelName); model_name present but not a string (null, number) so getModuleModelName returns null.

Common situations: Hand-writing a browser pipeline config and copying only the model_dir block; trimming configs for size and dropping model_name; converting a Python-side config where the field was optional.

Related errors

• RecResizeImg.image_shape is required in rec inference.yml
• OCR pipeline config text must decode to an object.
• ${modulePath}.model_dir must be null or an asset descriptor
• OCR pipeline config must define both "SubModules.TextDetecti
• Unexpected recognition channels: ${String(channels)}

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