PaddlePaddle/PaddleOCR · error

OCR pipeline config must be an object or YAML text.

Error message

OCR pipeline config must be an object or YAML text.

What it means

Thrown by parsePipelineConfigInput() when the non-string input is not a plain object — e.g. null, an array, a number, or a class instance. The API accepts exactly two shapes: a YAML string or a plain JS object; anything else is rejected before any field is read.

Source

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

    text_det_limit_type: runtimeDefaults.text_det_limit_type ?? "max",
    text_det_max_side_limit: runtimeDefaults.text_det_max_side_limit ?? 4000,
    text_det_thresh: runtimeDefaults.text_det_thresh ?? 0.3,
    text_det_box_thresh: runtimeDefaults.text_det_box_thresh ?? 0.6,
    text_det_unclip_ratio: runtimeDefaults.text_det_unclip_ratio ?? 2.0,
    text_rec_score_thresh: runtimeDefaults.text_rec_score_thresh ?? 0
  };
}

function parsePipelineConfigInput(input: unknown): YamlObject {
  if (typeof input === "string") {
    const parsed = yaml.load(input);
    if (!isPlainObject(parsed)) {
      throw new Error("OCR pipeline config text must decode to an object.");
    }
    return parsed;
  }
  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.`

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Pass a plain object literal or a YAML string
2. Guard the call site: skip or supply a default object when the config variable is null/undefined
3. If building config programmatically, verify Object.prototype.toString or typeof before calling

Example fix

// before
const config = configs[name]; // undefined when name missing
normalizeOcrPipelineConfig(config); // throws

// after
const config = configs[name] ?? { pipeline_name: "OCR" };
normalizeOcrPipelineConfig(config);

if (typeof input !== "string" && (typeof input !== "object" || input === null || Array.isArray(input))) {
  throw new TypeError("Pipeline config must be a YAML string or plain object");
}

function isPipelineConfigInput(input: unknown): input is string | Record<string, unknown> {
  return typeof input === "string" || (typeof input === "object" && input !== null && !Array.isArray(input));
}

When it happens

Trigger: Calling normalizeOcrPipelineConfig(null), with an array of config objects, with a JSON.parse result that is an array, or with undefined after a failed lookup (config from a map key that does not exist).

Common situations: Defaulting a missing config to null/undefined and passing it through; passing a Map or class-wrapped config; spreading an array of partial configs instead of merging into an object.

Related errors

• OCR pipeline config text must decode to an object.
• ${modulePath}.model_dir must be null or an asset descriptor
• Unsupported pipeline_name "${pipelineName}". PaddleOCR.js cu
• OCR pipeline config must define both "SubModules.TextDetecti
• Worker transport client requires a createWorker() factory.

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