PaddlePaddle/PaddleOCR · error

OCR pipeline config text must decode to an object.

Error message

OCR pipeline config text must decode to an object.

What it means

Thrown by parsePipelineConfigInput() when the input is a string but yaml.load() does not yield a plain object. YAML text that decodes to null, a number, a boolean, an array, or is effectively empty fails this check — the pipeline config must be a YAML mapping at the top level.

Solutions

1. Print the input string and run it through any YAML validator — confirm it decodes to a mapping
2. Ensure the config starts with mapping keys (e.g. pipeline_name:, SubModules:) and no leading '- '
3. If the file may be empty, check its length/content before parsing
4. Verify a remote fetch actually returned YAML (status 200, correct content) before parsing

Example fix

# before (config text)
- pipeline_name
- SubModules

# after (config text)
pipeline_name: OCR
SubModules:
  TextDetection: {}
  TextRecognition: {}

import { parse } from "yaml";
const doc = yamlText.trim() ? parse(yamlText) : undefined;
if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
  throw new Error("Pipeline config text is not a YAML mapping");
}

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

When it happens

Trigger: Passing "null", "" (empty string), "42", "- item" (a YAML list), or a multi-document YAML string to parseOcrPipelineConfigText/normalizeOcrPipelineConfig; a file read that returned only whitespace or a placeholder.

Common situations: Reading a config file that is empty or contains only comments; pasting an example YAML fragment that is a list of keys; fetch() of the config URL returning an error page body that happens to parse as a scalar.

Related errors

• OCR pipeline config must define both…
• .model_dir must be null or an asset descriptor object in…
• .model_name must be provided when .model_dir is set.
• OCR pipeline config must be an object or YAML text.
• only support yaml files for now, got

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

Appendix: source

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

  if (textType !== "general") {
    return runtimeDefaults;
  }
  return {
    text_det_limit_side_len: runtimeDefaults.text_det_limit_side_len ?? 960,
    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;
}

View on GitHub (pinned to 2661c7c0ef)