PaddlePaddle/PaddleOCR · error · Error

Worker mode requires ImageBitmap support in this browser.

Error message

Worker mode requires ImageBitmap support in this browser.

What it means

Thrown by sourceToWorkerPayload() when worker mode is requested but the runtime exposes neither the ImageBitmap constructor nor createImageBitmap(). The library transfers image data to the OCR worker as an ImageBitmap (transferable, zero-copy), so without this API the worker transport cannot be fed. This is a hard capability gate, not a runtime failure.

Source

Thrown at paddleocr-js/packages/core/src/platform/browser.ts:109

    };
  }

  const imageBitmap = await sourceToImageBitmap(source as ImageSource);
  const sourceImage = bitmapToSourceMat(cv, imageBitmap);
  return {
    width: imageBitmap.width,
    height: imageBitmap.height,
    mat: sourceImage.mat,
    dispose() {
      sourceImage.mat.delete();
      imageBitmap.close();
    }
  };
}

export async function sourceToWorkerPayload(source: ImageSource): Promise<WorkerPayloadResult> {
  if (typeof ImageBitmap === "undefined" || typeof createImageBitmap !== "function") {
    throw new Error("Worker mode requires ImageBitmap support in this browser.");
  }
  const imageBitmap = await sourceToClonedImageBitmap(source);
  return {
    payload: {
      kind: "imageBitmap",
      imageBitmap
    },
    transferables: [imageBitmap]
  };
}

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Feature-detect before enabling worker mode and fall back to main-thread OCR
2. Upgrade the browser/WebView to one supporting ImageBitmap (Chrome 50+, Firefox 42+, Safari 15+)
3. If a legacy target is mandatory, run OCR without the worker transport

Example fix

// before
const ocr = await PaddleOCR.create({ worker: true }); // throws on Safari 14

// after
const supportsWorker = typeof ImageBitmap !== "undefined" && typeof createImageBitmap === "function";
const ocr = await PaddleOCR.create({ worker: supportsWorker });

const workerImagesSupported =
  typeof ImageBitmap !== "undefined" && typeof createImageBitmap === "function";
// only enable worker mode when true

function supportsImageBitmap(): boolean {
  return typeof ImageBitmap === "function" || typeof createImageBitmap === "function";
}

When it happens

Trigger: Enabling worker mode (e.g. passing worker/workerMode options that route through sourceToWorkerPayload) on browsers predating ImageBitmap support: Safari < 15, legacy Edge, IE11, or older WebViews / embedded browsers.

Common situations: Enterprise apps that must support older iOS/Safari versions; Cordova/Electron with old Chromium; feature-detection being skipped because the app assumed 'all modern browsers have ImageBitmap'.

Related errors

• Worker mode requires OffscreenCanvas support in this browser
• worker mode requires Web Worker support in this environment.
• worker mode does not support a custom fetch implementation.
• worker must be a boolean or an options object.
• PaddleOCR worker instance has been disposed.

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