PaddlePaddle/PaddleOCR · error

worker must be a boolean or an options object.

Error message

worker must be a boolean or an options object.

What it means

resolveWorkerOptions() accepts only a boolean (true/false) or an options object (optionally with a createWorker function) for the worker setting. Any other type — string, number, null with wrong shape, array — falls through both branches and throws this error, because there is no meaningful interpretation of such a value.

Source

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

  }

  if (workerOption === true) {
    return {
      enabled: true,
      createWorker: null
    };
  }

  if (typeof workerOption === "object") {
    const opts = workerOption as Record<string, unknown>;
    return {
      enabled: true,
      createWorker:
        typeof opts.createWorker === "function" ? (opts.createWorker as () => Worker) : null
    };
  }

  throw new Error("worker must be a boolean or an options object.");
}

export function resolvePaddleOCROptions(options: Record<string, unknown> = {}): ResolvedOcrOptions {
  return {
    pipelineConfig: resolveConstructionOptions(options),
    ortOptions: normalizeOrtOptions((options.ortOptions || {}) as OrtOptions)
  };
}

export function cloneDefaultOcrConfig(): OcrModelConfig {
  return deepClone(DEFAULT_OCR_CONFIG);
}

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Use worker: true / false or an object like { createWorker: () => new Worker(new URL(...), { type: 'module' }) }.
2. Coerce env-derived values: worker: process.env.ENABLE_WORKER === 'true'.

Example fix

// before
const ocr = await PaddleOCR.create({ worker: 'true' });

// after
const ocr = await PaddleOCR.create({ worker: true });

type WorkerOption = boolean | { createWorker?: () => Worker };
function isValidWorkerOption(v: unknown): v is WorkerOption {
  if (typeof v === 'boolean') return true;
  if (v !== null && typeof v === 'object' && !Array.isArray(v)) return true;
  return false;
}

try {
  const ocr = await PaddleOCR.create(opts);
} catch (e) {
  if (e instanceof Error && e.message === 'worker must be a boolean or an options object.') {
    opts = { ...opts, worker: Boolean(opts.worker) };
    return PaddleOCR.create(opts);
  }
  throw e;
}

When it happens

Trigger: PaddleOCR.create({ worker: 'true' }), { worker: 1 }, { worker: () => new Worker(...) } (a function is neither boolean nor plain object as expected — pass { createWorker: fn } instead), or worker: null in some code paths.

Common situations: Reading the flag from an env var or CLI arg ('true' string) without converting; passing a worker factory directly instead of wrapping it in the options object.

Related errors

• worker mode does not support a custom fetch implementation.
• Conflicting values provided for ${label}: ${aliases.join(",
• ${modelRole} model selection must define model_name.
• OCR model selection must define both detection and recogniti
• Asset "${assetName}" must be an object.

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