{"record":{"id":"e9484927fbb7f804","repo":"run-llama/liteparse","slug":"liteparse-worker-failed-to-initialize-e","errorCode":null,"errorMessage":"liteparse worker failed to initialize: {e}","messagePattern":"liteparse worker failed to initialize: (.+?)","errorType":"exception","errorClass":"ParseError","httpStatus":null,"severity":"error","filePath":"packages/python/liteparse/_pool.py","lineNumber":258,"sourceCode":"        try:\n            status, data = worker.request(payload, self._timeout)\n        except _WorkerTimeout:\n            replace = True\n            timeout = self._timeout\n            raise ParseTimeoutError(\n                f\"parse of {source} exceeded {timeout}s; \"\n                \"the worker process was killed\",\n                source=source,\n                timeout=timeout,\n            ) from None\n        except _WorkerCrashed as e:\n            replace = True\n            raise ParseError(\n                f\"liteparse worker process died while parsing {source}: {e}\"\n            ) from None\n        except _WorkerInitFailed as e:\n            replace = True\n            raise ParseError(f\"liteparse worker failed to initialize: {e}\") from None\n        finally:\n            if replace:\n                self._retire_worker(worker)\n                if not self._closed:\n                    self._spawn_worker()\n            elif self._closed:\n                worker.stop()\n            else:\n                self._idle.put(worker)\n        if status == \"ok\":\n            return data\n        raise ParseError(data)\n\n    def warm_up(self) -> None:\n        \"\"\"Block until every worker has finished initializing.\n\n        Optional — the first parse per worker waits for init anyway. Useful\n        before latency-sensitive traffic or benchmarks.","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/run-llama/liteparse/blob/22d2dd8cd7f7b9320102b57ddaf0e663ff7d15a8/packages/python/liteparse/_pool.py#L240-L276","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the forwarded message after the colon — it is 'ExceptionType: detail' from the worker's native constructor","Verify the native component is installed for this platform (reinstall/upgrade the liteparse package, check arch matches)","Call parser.warm_up() at startup to surface init failures immediately instead of on the first parse","Try constructing a non-pooled LiteParse(...) with the same kwargs in-process to reproduce the error with a full traceback","Simplify the config kwargs passed to LiteParse until the worker initializes, then add them back one at a time"],"exampleFix":"# before\nparser = LiteParse(pool_size=4, ocr_engine=\"tesseract\")\nresult = parser.parse(doc)  # ParseError: worker failed to initialize\n\n# after\nparser = LiteParse(pool_size=4, ocr_engine=\"tesseract\")\nparser.warm_up()  # fails fast at startup with the real init error","handlingStrategy":"validation","validationCode":"from liteparse import LiteParse\nparser = LiteParse(pool_size=4)\nparser.warm_up()  # raises ParseError at startup if any worker fails to init","typeGuard":null,"tryCatchPattern":"from liteparse.types import ParseError\ntry:\n    parser.warm_up()\nexcept ParseError as e:\n    print(\"worker init failed:\", e)  # inspect forwarded ExceptionType: detail","preventionTips":["Call warm_up() immediately after constructing a pooled parser","Pin the liteparse version and confirm the native binary installs for your platform/arch","Keep parent and worker environments identical (same image, PATH, TESSDATA_PREFIX)","Validate config kwargs once against a non-pooled LiteParse before deploying"],"tags":["initialization","worker-pool","subprocess","native-library"],"backgroundTag":"module-init-failed","analyzedSha":"22d2dd8cd7f7b9320102b57ddaf0e663ff7d15a8","analyzedAt":"2026-09-08T06:09:49.009Z","contentChangedAt":"2026-09-08T06:09:49.009Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}