PaddlePaddle/PaddleOCR · error · Error

Worker mode requires OffscreenCanvas support in this browser

Error message

Worker mode requires OffscreenCanvas support in this browser.

What it means

Thrown inside the OCR worker (worker.ts imageBitmapToImageData) when OffscreenCanvas is not a constructor. The worker converts the transferred ImageBitmap into ImageData for OpenCV.js using an OffscreenCanvas, since DOM canvas is unavailable in worker scope. This gate fires when the browser supports ImageBitmap but not OffscreenCanvas (or when OffscreenCanvas is disabled by flag/policy).

Source

Thrown at paddleocr-js/packages/core/src/platform/worker.ts:17

/*
 * Copyright (c) 2026 PaddlePaddle Authors. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0
 */

import type { OpenCv, Mat } from "@techstark/opencv-js";
import type { SourceMatResult } from "./browser";
import { ensureServedFromHttp } from "./browser";

export interface WorkerSourcePayload {
  kind: "imageBitmap";
  imageBitmap: ImageBitmap;
}

function imageBitmapToImageData(imageBitmap: ImageBitmap): ImageData {
  if (typeof OffscreenCanvas !== "function") {
    throw new Error("Worker mode requires OffscreenCanvas support in this browser.");
  }
  const canvas = new OffscreenCanvas(imageBitmap.width, imageBitmap.height);
  const ctx = canvas.getContext("2d", { willReadFrequently: true });
  if (!ctx) {
    throw new Error("Failed to create a 2D canvas context in the OCR worker.");
  }
  ctx.drawImage(imageBitmap, 0, 0);
  return ctx.getImageData(0, 0, imageBitmap.width, imageBitmap.height);
}

function imageDataToMat(cv: OpenCv, imageData: ImageData): Mat {
  return cv.matFromArray(imageData.height, imageData.width, cv.CV_8UC4, imageData.data);
}

function isWorkerSourcePayload(source: unknown): source is WorkerSourcePayload {
  if (typeof source !== "object" || source === null) return false;
  const candidate = source as Record<string, unknown>;
  return (

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Feature-detect OffscreenCanvas (in a worker scope) before enabling worker mode and fall back to main-thread OCR
2. Serve the main bundle that detects support and disables the worker path for those browsers
3. Update Safari to >= 16.4 or use a Chromium/Firefox >= 105 browser

Example fix

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

// after
const offscreenOK = (() => {
  try { return typeof OffscreenCanvas === "function"; } catch { return false; }
})();
const ocr = await PaddleOCR.create({ worker: offscreenOK });

function offscreenCanvasSupportedInWorker(): Promise<boolean> {
  return new Promise(resolve => {
    try {
      const w = new Worker(URL.createObjectURL(new Blob([
        "self.postMessage(typeof OffscreenCanvas === 'function')"
      ], { type: 'text/javascript' })));
      w.onmessage = e => { resolve(Boolean(e.data)); w.terminate(); };
      w.onerror = () => resolve(false);
    } catch { resolve(false); }
  });
}

const hasOffscreenCanvas = typeof OffscreenCanvas === "function";

When it happens

Trigger: Worker mode enabled on browsers lacking OffscreenCanvas: Safari < 16.4, older Firefox versions; headless/automation environments where the feature is disabled; some locked-down enterprise browser policies.

Common situations: Safari 15/16.0-16.3 users (ImageBitmap yes, OffscreenCanvas no); older Android WebViews; CI browser matrices that include older versions.

Related errors

• Worker mode requires ImageBitmap support in this browser.
• worker mode requires Web Worker support in this environment.
• Failed to create a 2D canvas context in the OCR worker.
• worker mode does not support a custom fetch implementation.
• worker must be a boolean or an options object.

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