run-llama/liteparse · error · ParseError

liteparse worker failed to initialize

Error message

liteparse worker failed to initialize: {e}

What it means

Raised as ParseError when a pool worker subprocess reports that constructing its native parser failed during initialization. The worker catches the exception in _worker_main, sends an ('init_error', msg) frame, and the parent converts it to _WorkerInitFailed and then ParseError. Like the crash case, the failed worker is retired and replaced automatically.

Solutions

1. Read the forwarded message after the colon — it is 'ExceptionType: detail' from the worker's native constructor
2. Verify the native component is installed for this platform (reinstall/upgrade the liteparse package, check arch matches)
3. Call parser.warm_up() at startup to surface init failures immediately instead of on the first parse
4. Try constructing a non-pooled LiteParse(...) with the same kwargs in-process to reproduce the error with a full traceback
5. Simplify the config kwargs passed to LiteParse until the worker initializes, then add them back one at a time

Example fix

# before
parser = LiteParse(pool_size=4, ocr_engine="tesseract")
result = parser.parse(doc)  # ParseError: worker failed to initialize

# after
parser = LiteParse(pool_size=4, ocr_engine="tesseract")
parser.warm_up()  # fails fast at startup with the real init error

from liteparse import LiteParse
parser = LiteParse(pool_size=4)
parser.warm_up()  # raises ParseError at startup if any worker fails to init

from liteparse.types import ParseError
try:
    parser.warm_up()
except ParseError as e:
    print("worker init failed:", e)  # inspect forwarded ExceptionType: detail

When it happens

Trigger: Calling parse() on a pooled LiteParse where the worker could not construct LiteParse's native parser (the _NativeLiteParse(**config) call in the child raised): invalid config kwargs, missing/ corrupted native shared library, or a missing data/resource file (e.g. Tesseract data) in the child environment.

Common situations: Deployment mismatch where the package is installed but its native binary/shared lib is absent or wrong-arch; config options passed that the native layer rejects; workers initializing in a different environment (container, restricted PATH, missing TESSDATA_PREFIX) than the parent.

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/e9484927fbb7f804. Report an issue: GitHub.

Appendix: source

Thrown at packages/python/liteparse/_pool.py:258

        try:
            status, data = worker.request(payload, self._timeout)
        except _WorkerTimeout:
            replace = True
            timeout = self._timeout
            raise ParseTimeoutError(
                f"parse of {source} exceeded {timeout}s; "
                "the worker process was killed",
                source=source,
                timeout=timeout,
            ) from None
        except _WorkerCrashed as e:
            replace = True
            raise ParseError(
                f"liteparse worker process died while parsing {source}: {e}"
            ) from None
        except _WorkerInitFailed as e:
            replace = True
            raise ParseError(f"liteparse worker failed to initialize: {e}") from None
        finally:
            if replace:
                self._retire_worker(worker)
                if not self._closed:
                    self._spawn_worker()
            elif self._closed:
                worker.stop()
            else:
                self._idle.put(worker)
        if status == "ok":
            return data
        raise ParseError(data)

    def warm_up(self) -> None:
        """Block until every worker has finished initializing.

        Optional — the first parse per worker waits for init anyway. Useful
        before latency-sensitive traffic or benchmarks.

View on GitHub (pinned to 22d2dd8cd7)