What causes "Initialization did not complete. Call initialize() first." in PaddlePaddle/PaddleOCR?

Call and await initialize() explicitly, and let its errors propagate — do not catch-and-continue

Initialization did not complete. Call initialize() first.

Error message

Initialization did not complete. Call initialize() first.

What it means

Thrown by OcrPipelineRunner.predict() after it lazily awaited initialize() yet detModel, recModel, or the cv/ort handles are still missing. The guard exists because initialize() can return without fully populating state (a swallowed failure, an aborted init, or a derived class overriding initialize incompletely). It distinguishes 'not initialized yet' (auto-fixed) from 'initialization ran but did not complete' (this error).

Source

Thrown at paddleocr-js/packages/core/src/pipelines/ocr/core.ts:209

  }

  getModelConfig(): OcrModelConfig {
    return this.modelConfig;
  }

  async predict(input: unknown, params: OcrRuntimeParamsInput = {}): Promise<OcrResult[]> {
    if (!this.sourceToMat) {
      throw new Error("PaddleOCR source adapter is not configured.");
    }
    if (!this.detModel || !this.recModel || !this.cv || !this.ort) {
      await this.initialize();
    }

    const cv = this.cv;
    const detModel = this.detModel;
    const recModel = this.recModel;
    if (!cv || !detModel || !recModel) {
      throw new Error("Initialization did not complete. Call initialize() first.");
    }

    const sources = Array.isArray(input) ? input : [input];
    const sourceToMat = this.sourceToMat;
    const pipelineBatchSize = Math.max(1, Math.floor(this.pipelineConfig.pipelineBatchSize) || 1);
    const sourceBatches = chunkArray(sources, pipelineBatchSize);

    const totalStart = nowMs();
    const resolved = getOcrRuntimeParams(this.modelConfig, this.runtimeDefaults, params);

    let sumDetMs = 0;
    let sumRecMs = 0;
    const partials: Array<{
      image: { width: number; height: number };
      items: OcrResultItem[];
      detectedBoxes: number;
      recognizedCount: number;
    }> = [];

View on GitHub (pinned to 2661c7c0ef)

Solutions

Call and await initialize() explicitly, and let its errors propagate — do not catch-and-continue
Check getInitializationSummary() after init to confirm all models and backends came up
If initialization failed, re-create the runner (or re-run initialize) instead of retrying predict on the half-built one
For subclass authors: ensure initialize() assigns detModel, recModel, cv, and ort before resolving

Example fix

// before
runner.initialize().catch(e => console.warn(e)); // swallowed
await runner.predict(img); // throws: initialization did not complete

// after
try { await runner.initialize(); } catch (e) { /* report and stop */ throw e; }
await runner.predict(img);

Defensive patterns

Strategy: retry

Validate before calling

await runner.initialize(); // let errors propagate
const summary = runner.getInitializationSummary();
if (!summary?.detModel || !summary?.recModel) {
  throw new Error("Initialization incomplete — do not call predict");
}

Type guard

function isRunnerInitialized(runner: { detModel: unknown; recModel: unknown; cv: unknown; ort: unknown }): boolean {
  return Boolean(runner.detModel && runner.recModel && runner.cv && runner.ort);
}

Try / catch

try { await runner.predict(input); } catch (e) {
  if (e instanceof Error && /Initialization did not complete/.test(e.message)) {
    await runner.initialize(); // fresh, full init; then retry predict once
    await runner.predict(input);
  } else throw e;
}

Prevention

Await initialize() explicitly once and let failures stop the flow — never catch-and-continue
Verify getInitializationSummary() reports all models before first predict
Recreate the runner after a failed init rather than reusing half-built state

When it happens

Trigger: Calling predict() when a previous initialize() failed partway (e.g. det model loaded, rec download threw) and the failure was caught and ignored; a subclass overriding initialize() without calling super or without assigning all four fields; concurrent predict() calls where one init path errored.

Common situations: Wrapping initialize() in a try-catch that logs-and-continues, leaving the runner half-initialized; intermittent model fetch failures in CI; disposed/re-initialized runners where ort or cv was torn down but detModel reference survived.

Related errors

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