{"record":{"id":"0e7ea305425424d4","repo":"PaddlePaddle/PaddleOCR","slug":"worker-mode-requires-web-worker-support-in-this-en","errorCode":null,"errorMessage":"worker mode requires Web Worker support in this environment.","messagePattern":"worker mode requires Web Worker support in this environment\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"paddleocr-js/packages/core/src/pipelines/ocr/worker-backed.ts","lineNumber":17,"sourceCode":"/*\n * Copyright (c) 2026 PaddlePaddle Authors. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { sourceToWorkerPayload } from \"../../platform/browser\";\nimport { createWorkerTransportClient } from \"../../worker/client\";\nimport type { WorkerTransportClient, WorkerOptions } from \"../../worker/client\";\nimport type { OcrModelConfig, OcrRuntimeParamsInput } from \"./runtime-params\";\nimport type { InitializationSummary, OcrResult, OcrPipelineRunnerOptions } from \"./core\";\nimport { cloneDefaultOcrConfig } from \"./shared\";\n\ndeclare const __ORT_WASM_CDN_PREFIX__: string | undefined;\n\nfunction createDefaultWorker(): Worker {\n  if (typeof Worker !== \"function\") {\n    throw new Error(\"worker mode requires Web Worker support in this environment.\");\n  }\n  return new Worker(new URL(\"./worker-entry.ts\", import.meta.url), {\n    type: \"module\"\n  });\n}\n\nexport class WorkerBackedPaddleOCR {\n  private options: OcrPipelineRunnerOptions;\n  private lastInitializationSummary: InitializationSummary | null;\n  private modelConfig: OcrModelConfig;\n  private transportClient: WorkerTransportClient;\n  private initPromise: Promise<InitializationSummary> | null;\n  private disposed: boolean;\n\n  constructor(options: OcrPipelineRunnerOptions, transportClient: WorkerTransportClient) {\n    this.options = options;\n    this.lastInitializationSummary = null;\n    this.modelConfig = cloneDefaultOcrConfig();","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr-js/packages/core/src/pipelines/ocr/worker-backed.ts#L1-L35","documentation":"In worker mode, if no custom createWorker is supplied, createDefaultWorker() constructs the bundled worker-entry module. It first checks that the global Worker constructor is a function; in environments without Web Workers (Node.js, some SSR/prerender contexts, restricted sandboxed iframes) it is undefined or not callable, so it throws instead of producing a confusing 'Worker is not defined' ReferenceError.","triggerScenarios":"Running PaddleOCR.create({ worker: true }) in Node.js, Jest/vitest without jsdom+worker polyfills, or during SSR/prerendering; sandboxed iframes that block workers.","commonSituations":"Unit tests executing library imports against Node; Next.js/Nuxt server-side render paths accidentally invoking create(); assuming Node's worker_threads satisfies the browser Worker API.","solutions":["Only enable worker mode in browser code paths (guard with typeof Worker !== 'undefined').","In tests, use an environment with Worker support (real browser, Playwright/WebdriverIO) or polyfill Worker.","For Node, run without worker mode (worker: false) if that path is supported for your use case."],"exampleFix":"// before\nconst ocr = await PaddleOCR.create({ worker: true }); // called in Node/SSR\n\n// after\nconst ocr = await PaddleOCR.create({\n  worker: typeof Worker !== 'undefined'\n});","handlingStrategy":"type-guard","validationCode":"// Only request worker mode where Workers exist\nif (typeof Worker !== 'function') {\n  opts = { ...opts, worker: false };\n}\nconst ocr = await PaddleOCR.create(opts);","typeGuard":"function supportsWebWorkers(): boolean {\n  return typeof globalThis.Worker === 'function';\n}","tryCatchPattern":"try {\n  const ocr = await PaddleOCR.create({ worker: true });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('requires Web Worker support')) {\n    return PaddleOCR.create({ worker: false }); // run on the main thread instead\n  }\n  throw e;\n}","preventionTips":["Gate all OCR imports and create() calls behind browser-only code paths (dynamic import in useEffect / onMount).","In SSR frameworks, ensure the OCR module is only loaded client-side."],"tags":["worker","environment","node","ssr","browser-support"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}