PaddlePaddle/PaddleOCR · error

PaddleOCR.js requires an HTTP(S) origin so model assets can

Error message

PaddleOCR.js requires an HTTP(S) origin so model assets can be fetched.

What it means

The browser platform guard ensureServedFromHttp() checks globalThis.location.protocol and throws when it is 'file:'. Model assets (ONNX weights, configs) must be fetched over HTTP(S); under the file: protocol fetch is blocked or unreliable due to browser security rules (CORS/opaque origins), so the library refuses to continue.

Source

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

  width: number;
  height: number;
  mat: Mat;
  dispose(): void;
}

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

export interface WorkerPayloadResult {
  payload: WorkerPayload;
  transferables: Transferable[];
}

export function ensureServedFromHttp(): void {
  if (globalThis.location.protocol === "file:") {
    throw new Error("PaddleOCR.js requires an HTTP(S) origin so model assets can be fetched.");
  }
}

function hasDomConstructor(name: string): boolean {
  return typeof (globalThis as Record<string, unknown>)[name] !== "undefined";
}

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");

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Serve the app over HTTP: npx serve, python -m http.server, or your bundler dev server.
2. In Electron, load content via http(s) or a custom app:// protocol registered as standard/secure.
3. For static demos, use a hosting provider or GitHub Pages.

Example fix

# before
open index.html  # file:// URL -> throws

# after
npx serve .
# then open http://localhost:3000

// Refuse to boot the OCR app from file://
if (typeof location !== 'undefined' && location.protocol === 'file:') {
  showBanner('Serve this app over http(s) — e.g. `npx serve .` — model downloads require an HTTP origin.');
}

function isHttpOrigin(): boolean {
  return typeof globalThis.location === 'undefined' || globalThis.location.protocol !== 'file:';
}

try {
  const ocr = await PaddleOCR.create();
} catch (e) {
  if (e instanceof Error && e.message.includes('HTTP(S) origin')) {
    showUserError('Please open this page via a local web server, not by double-clicking the HTML file.');
    return;
  }
  throw e;
}

When it happens

Trigger: Opening an HTML page directly from disk (file:///C:/...index.html) that calls PaddleOCR.create() or predict(); local demos opened by double-clicking instead of serving.

Common situations: Quick local testing without a dev server; Electron apps loading content via file:// without a custom protocol; distributable HTML attachments opened from the filesystem.

Related errors

• Failed to create a 2D canvas context.
• Failed to download ${asset.url}: HTTP ${String(response.stat
• Expected a JSON response body.
• PaddleOCR official API request failed.
• Response body is missing data.

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