{"record":{"id":"690c15486b41d08a","repo":"PaddlePaddle/PaddleOCR","slug":"worker-must-be-a-boolean-or-an-options-object","errorCode":null,"errorMessage":"worker must be a boolean or an options object.","messagePattern":"worker must be a boolean or an options object\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"paddleocr-js/packages/core/src/pipelines/ocr/shared.ts","lineNumber":625,"sourceCode":"  }\n\n  if (workerOption === true) {\n    return {\n      enabled: true,\n      createWorker: null\n    };\n  }\n\n  if (typeof workerOption === \"object\") {\n    const opts = workerOption as Record<string, unknown>;\n    return {\n      enabled: true,\n      createWorker:\n        typeof opts.createWorker === \"function\" ? (opts.createWorker as () => Worker) : null\n    };\n  }\n\n  throw new Error(\"worker must be a boolean or an options object.\");\n}\n\nexport function resolvePaddleOCROptions(options: Record<string, unknown> = {}): ResolvedOcrOptions {\n  return {\n    pipelineConfig: resolveConstructionOptions(options),\n    ortOptions: normalizeOrtOptions((options.ortOptions || {}) as OrtOptions)\n  };\n}\n\nexport function cloneDefaultOcrConfig(): OcrModelConfig {\n  return deepClone(DEFAULT_OCR_CONFIG);\n}\n","sourceCodeStart":607,"sourceCodeEnd":638,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr-js/packages/core/src/pipelines/ocr/shared.ts#L607-L638","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use worker: true / false or an object like { createWorker: () => new Worker(new URL(...), { type: 'module' }) }.","Coerce env-derived values: worker: process.env.ENABLE_WORKER === 'true'."],"exampleFix":"// before\nconst ocr = await PaddleOCR.create({ worker: 'true' });\n\n// after\nconst ocr = await PaddleOCR.create({ worker: true });","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"type WorkerOption = boolean | { createWorker?: () => Worker };\nfunction isValidWorkerOption(v: unknown): v is WorkerOption {\n  if (typeof v === 'boolean') return true;\n  if (v !== null && typeof v === 'object' && !Array.isArray(v)) return true;\n  return false;\n}","tryCatchPattern":"try {\n  const ocr = await PaddleOCR.create(opts);\n} catch (e) {\n  if (e instanceof Error && e.message === 'worker must be a boolean or an options object.') {\n    opts = { ...opts, worker: Boolean(opts.worker) };\n    return PaddleOCR.create(opts);\n  }\n  throw e;\n}","preventionTips":["Type your config with the union boolean | { createWorker?(): Worker } so TypeScript rejects strings at compile time.","Coerce env-var/CLI-derived flags (worker: flag === 'true') at the config boundary."],"tags":["worker","configuration","validation","type-error"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}