# Troubleshooting

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

Source: https://openbooks.lumeo.co.in/docs/troubleshooting

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 [#check-the-installation]

~~~bash
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.

| Symptom | Action |
| --- | --- |
| Node.js reports `python_not_found` or `engine_not_installed` | Set `OPENBOOKS_PYTHON` to the interpreter in the environment where `python -m openbooks engine-info` works. |
| `engine_version` or schema mismatch | Compare the wrapper version and engine-info output, then reinstall compatible versions in the same job image. |
| Layout provider is missing from an editable checkout | Install 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 [#diagnose-a-document-run]

| Symptom | Action |
| --- | --- |
| Missing opening balance or ambiguous dates | Supply the authoritative opening balance or known date convention. Use the [sample run](/docs/quickstart) to test the same invocation on a known input. |
| Unknown layout | Compare the original export with the [format matrix](/docs/formats) and verify the installed provider. |
| Scan requires OCR or model files | Install 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 PDF | For 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.done` | Keep 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](/docs/refusals) to look for a layout, parameter, or evidence issue in the export.

## Report a reproducible issue [#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.
