What causes "OCR worker is not initialized." in PaddlePaddle/PaddleOCR?

Always await the promise returned by PaddleOCR.create()/initialize() before calling predict().

OCR worker is not initialized.

Error message

OCR worker is not initialized.

What it means

Inside the OCR Web Worker, the message handler keeps a module-level `ocr` instance created by the 'init' message and cleared by 'dispose'. If a 'predict' message arrives while `ocr` is null — never initialized, or already disposed — handlePredict throws this error, which is serialized back to the main thread as a rejected RPC.

Source

Thrown at paddleocr-js/packages/core/src/pipelines/ocr/worker-entry.ts:31

  let ocr: OcrPipelineRunner | null = null;

  async function handleInit(payload: Record<string, unknown>) {
    await ocr?.dispose();
    ocr = new OcrPipelineRunner({
      ...(payload.options as OcrPipelineRunnerOptions),
      ensureServedFromHttp,
      sourceToMat: sourcePayloadToMat
    });
    const summary = await ocr.initialize();
    return {
      summary,
      modelConfig: ocr.getModelConfig()
    };
  }

  async function handlePredict(payload: Record<string, unknown>) {
    if (!ocr) {
      throw new Error("OCR worker is not initialized.");
    }
    const sources = payload.sources;
    return ocr.predict(sources, (payload.params || {}) as OcrRuntimeParamsInput);
  }

  async function handleDispose() {
    await ocr?.dispose();
    ocr = null;
    return {};
  }

  return async function handleMessage(type: string, payload: Record<string, unknown>) {
    switch (type) {
      case "init":
        return handleInit(payload);
      case "predict":
        return handlePredict(payload);
      case "dispose":

View on GitHub (pinned to 2661c7c0ef)

Solutions

Always await the promise returned by PaddleOCR.create()/initialize() before calling predict().
Ensure dispose() is not called while predictions are in flight (await them first).
After disposal, create and initialize a new instance for further work.

Example fix

// before
const ocr = await PaddleOCR.create();
void ocr.initialize(); // not awaited
await ocr.predict(image); // may throw

// after
const ocr = await PaddleOCR.create();
await ocr.initialize();
await ocr.predict(image);

Defensive patterns

Strategy: validation

Validate before calling

// Always await initialization before predicting
const ocr = await PaddleOCR.create();
await ocr.initialize();
const result = await ocr.predict(image);

Try / catch

try {
  await ocr.predict(image);
} catch (e) {
  if (e instanceof Error && e.message === 'OCR worker is not initialized.') {
    await ocr.initialize(); // or recreate the instance
    return ocr.predict(image);
  }
  throw e;
}

Prevention

Expose only an async getReadyOcr() helper in your app that memoizes the initialized instance.
Never fire-and-forget initialize(); every predict call site should be downstream of the init promise.

When it happens

Trigger: Calling predict() on a WorkerBackedPaddleOCR before awaiting initialize(); calling predict() concurrently with dispose(); a transport-level race where the predict message is delivered after dispose.

Common situations: Fire-and-forget init (not awaiting the initialize()/create() promise); shared worker instance disposed by another part of the app mid-batch; retry logic that predicts after teardown.

Related errors

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