PaddlePaddle/PaddleOCR · error

Unsupported image source. Use a Blob, ImageBitmap, ImageData

Error message

Unsupported image source. Use a Blob, ImageBitmap, ImageData, canvas, or img.

What it means

sourceToImageBitmap() accepts a closed set of image source types: Blob, ImageBitmap, ImageData, HTMLCanvasElement, and HTMLImageElement. Anything else — a plain object, a string URL, a Buffer, an OffscreenCanvas, a VideoFrame, TypedArray pixel data — falls through all instanceof checks and hits this terminal error telling you which types are supported.

Source

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

export async function sourceToImageBitmap(source: ImageSource): Promise<ImageBitmap> {
  if (typeof ImageBitmap !== "undefined" && source instanceof ImageBitmap) return source;
  if (source instanceof Blob) return createImageBitmap(source);
  if (hasDomConstructor("HTMLCanvasElement") && source instanceof HTMLCanvasElement) {
    return createImageBitmap(source);
  }
  if (source instanceof ImageData) {
    const canvas = document.createElement("canvas");
    canvas.width = source.width;
    canvas.height = source.height;
    const ctx = canvas.getContext("2d");
    if (!ctx) throw new Error("Failed to create a 2D canvas context.");
    ctx.putImageData(source, 0, 0);
    return createImageBitmap(canvas);
  }
  if (hasDomConstructor("HTMLImageElement") && source instanceof HTMLImageElement) {
    return createImageBitmap(source);
  }
  throw new Error("Unsupported image source. Use a Blob, ImageBitmap, ImageData, canvas, or img.");
}

async function sourceToClonedImageBitmap(source: ImageSource): Promise<ImageBitmap> {
  if (typeof ImageBitmap !== "undefined" && source instanceof ImageBitmap) {
    return createImageBitmap(source);
  }
  return sourceToImageBitmap(source);
}

export function bitmapToSourceMat(
  cv: OpenCv,
  imageBitmap: ImageBitmap
): { canvas: HTMLCanvasElement; mat: Mat } {
  const canvas = document.createElement("canvas");
  canvas.width = imageBitmap.width;
  canvas.height = imageBitmap.height;
  const ctx = canvas.getContext("2d", { willReadFrequently: true });
  if (!ctx) throw new Error("Failed to create a 2D canvas context.");

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. For URLs, fetch and convert first: const blob = await (await fetch(url)).blob(); then pass the Blob.
2. For video, draw the current frame to a canvas and pass the canvas.
3. For raw pixels, construct ImageData (or a Blob) instead of passing the raw TypedArray.

Example fix

// before
const result = await ocr.predict('https://example.com/doc.png');

// after
const blob = await (await fetch('https://example.com/doc.png')).blob();
const result = await ocr.predict(blob);

type SupportedImageSource = Blob | ImageBitmap | ImageData | HTMLCanvasElement | HTMLImageElement;
function isSupportedImageSource(src: unknown): src is SupportedImageSource {
  if (typeof Blob !== 'undefined' && src instanceof Blob) return true;
  if (typeof ImageBitmap !== 'undefined' && src instanceof ImageBitmap) return true;
  if (typeof ImageData !== 'undefined' && src instanceof ImageData) return true;
  if (typeof HTMLCanvasElement !== 'undefined' && src instanceof HTMLCanvasElement) return true;
  if (typeof HTMLImageElement !== 'undefined' && src instanceof HTMLImageElement) return true;
  return false;
}

try {
  await ocr.predict(source);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported image source')) {
    const blob = typeof source === 'string' ? await (await fetch(source)).blob() : source;
    return ocr.predict(blob as Blob);
  }
  throw e;
}

When it happens

Trigger: Calling predict('https://example.com/img.png') (URL string not supported), predict(new Uint8Array(...)), predict(video element or VideoFrame), or passing Node-side structures when the browser build is used.

Common situations: Assuming URLs are accepted as sources; porting code from server-side OCR APIs that take paths/buffers; trying to feed OffscreenCanvas or video frames.

Related errors

• Failed to create a 2D canvas context.
• ${modulePath}.model_dir must be null or an asset descriptor
• PaddleOCR source adapter is not configured.
• 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/2fdd1af403abed93. Report an issue: GitHub.