Skip to Content
Open Books for developers

Troubleshooting

Diagnose missing Python providers, mismatched engine versions, OCR and model setup, file refusals and interrupted streams.

Start by finding the last completed step. If the command or wrapper cannot find the engine, check installation. If you received a JSON decision, read its status and message. If a batch stopped partway through, use the individual decisions to identify which files still need processing.

Check the installation

python --version
python -m openbooks engine-info
python -m openbooks doctor --json

Use Python 3.11 or newer and check that engine-info reports openbooks.v1 and the expected layouts. Read the diagnostics JSON for the failing check and its message. If you installed the npm CLI, run openbooks doctor to check which engine Node.js discovers. Add --deep when you need to test model loading.

SymptomAction
Node.js reports python_not_found or engine_not_installedSet OPENBOOKS_PYTHON to the interpreter in the environment where python -m openbooks engine-info works.
engine_version or schema mismatchCompare the wrapper version and engine-info output, then reinstall compatible versions in the same job image.
Layout provider is missing from an editable checkoutInstall with python -m pip install -e packages/py/openbooks to register it. Check engine-info again.

To find the interpreter for your current environment, run python -c "import sys; print(sys.executable)". Use that absolute path for OPENBOOKS_PYTHON when the Python command works and the Node.js wrapper is discovering a different installation.

Diagnose a document run

SymptomAction
Missing opening balance or ambiguous datesSupply the authoritative opening balance or known date convention. Use the sample run to test the same invocation on a known input.
Unknown layoutCompare the original export with the format matrix and verify the installed provider.
Scan requires OCR or model filesInstall the scan extra, make the OCR language assets available, and run doctor --deep for model setup. Check any model directory override.
npm asks for a model on a text-layer PDFFor a job using the base engine, set model: false in Node.js or pass --no-model to the npm CLI.
HTTP stream ends before run.doneKeep completed file decisions and mark missing ones interrupted. Check service logs, timeouts, and proxy buffering before retrying.

If a known sample releases and your export refuses, use the refusal code to look for a layout, parameter, or evidence issue in the export.

Report a reproducible issue

  1. Record the package and engine versions, input type and expected layout, and the command or options.
  2. Include the exact refusal or error code, the message, and the outcome you expected.
  3. Reproduce with a synthetic file where possible. If you share an excerpt, redact account numbers and other identifying financial details.
View this page as Markdown