run-llama/liteparse · error · Error

liteparse worker process died while parsing

Error message

liteparse worker process died while parsing ${source}: ${e.message}

What it means

If the worker child process dies unexpectedly during a parse (crash, OOM kill, native segfault in PDFium), the pool wraps it in this error naming the source document and the underlying message. The dead worker is retired and replaced, so the pool can keep serving other parses. Unlike a timeout, this indicates an abnormal termination rather than an elapsed-time limit.

Solutions

1. Catch the error and retry the parse once with a fresh pool/worker to rule out a transient kill.
2. Reduce memory pressure: lower poolSize or parse documents sequentially.
3. Check dmesg/container logs for OOM kills and raise the memory limit.
4. Verify the input opens in another PDF viewer; isolate corrupt documents before parsing.
5. Upgrade LiteParse in case the crash is a fixed native bug; report the crashing document to the maintainers.

Example fix

// before
const result = await pool.parse(buf, 'doc.pdf');
// after
let result;
try {
  result = await pool.parse(buf, 'doc.pdf');
} catch (e) {
  if (e.message.startsWith('liteparse worker process died')) {
    result = await newPool.parse(buf, 'doc.pdf'); // retry once
  } else throw e;
}

import { statSync } from 'fs';
const mb = statSync(path).size / 1e6;
if (mb > 500) console.warn(`${path} is very large (${mb}MB); risk of worker OOM — consider splitting`);

try {
  result = await pool.parse(buf, source);
} catch (e) {
  if (e.message.startsWith('liteparse worker process died')) {
    result = await pool.parse(buf, source); // pool replaces retired worker; retry once
  } else throw e;
}

When it happens

Trigger: Worker process OOM-killed by the OS on a very large PDF; segfault or panic in native code (PDFium) while parsing a malformed/corrupt document; the worker being killed externally (container memory limits, cgroup OOM).

Common situations: Memory-capped Docker containers parsing large scanned PDFs; corrupt or fuzzed PDF inputs crashing PDFium; system-wide memory pressure under concurrent heavy parses.

Related errors

• liteparse worker process died while parsing
• parseTimeoutMs requires poolSize
• poolSize must be an integer >= 1
• parseTimeoutMs must be > 0
• parser pool is closed

AI-assisted analysis of run-llama/liteparse@22d2dd8cd7 (2026-09-08). Data as JSON: /api/errors/7516a50c0517aec5. Report an issue: GitHub.

Appendix: source

Thrown at packages/node/src/pool.ts:269

  async parse(payload: string | Buffer, source: string): Promise<ParseResult> {
    if (this.closed) throw new Error("parser pool is closed");
    const worker = await this.acquire();
    try {
      await worker.ready();
      const result = await worker.request(payload, this.timeoutMs);
      this.release(worker);
      return result;
    } catch (e) {
      this.retire(worker);
      if (e instanceof WorkerTimeout) {
        throw new ParseTimeoutError(
          `parse of ${source} exceeded ${this.timeoutMs}ms; the worker process was killed`,
          source,
          this.timeoutMs!,
        );
      }
      if (e instanceof WorkerCrashed) {
        throw new Error(
          `liteparse worker process died while parsing ${source}: ${e.message}`,
        );
      }
      throw e;
    }
  }

  /** Resolves when every worker is initialized. Optional — the first parse
   * per worker waits for init anyway. */
  async warmUp(): Promise<void> {
    await Promise.all([...this.workers].map((w) => w.ready()));
  }

  /** Shut down all workers. Idempotent. Busy workers are stopped as their
   * in-flight parses finish. */
  close(): void {
    if (this.closed) return;
    this.closed = true;

View on GitHub (pinned to 22d2dd8cd7)