Troubleshooting

Installation

pip install fails on onnxruntime

Almost always an unsupported platform or interpreter. Confirm python3 --version is 3.10 or newer, and that you are not on an Intel Mac — onnxruntime 1.18+ ships no x86-64 macOS wheels. Use the Docker CPU image there.

tuzkaocr: command not found

The virtual environment is not active. Re-run source .venv/bin/activate.

A new model or setting seems to be missing after upgrading

Reinstall with pip install --force-reinstall --no-deps . — see Upgrading.

tuzkaocr.env is ignored

Expected for an installed package. Use environment variables or a .env in the working directory — see where settings come from.

Output quality

Text is garbled, or lines are missing

In order:

1. Check the domain — see Models and domains.
2. Leave adaptive downsampling on (do not pass --no-adaptive).
3. Try --height-scale 1.5 if crops clip ascenders or descenders.
4. Check the scan. Below roughly 200 dpi, no setting recovers the page.

A scan is sideways or upside down

Pass --orientation auto (TUZKAOCR_ORIENTATION=auto). If upside-down pages still slip through, also set TUZKAOCR_ORIENTATION_RECHECK=on — see page orientation.

Pale carbon copies or faint typewriter text are hard to read

Try --contrast auto (TUZKAOCR_CONTRAST=auto) — see contrast normalisation.

Columns or articles are read in the wrong order

Try TUZKAOCR_READING_ORDER=basic (CLI --reading-order basic) — see reading order.

A newspaper title is garbled or missing

Check that large text is not disabled. Ornate display faces may still be misread.

Kramarky output is poor on a newspaper

kramarky is for kramarky broadsheets only. Use the default domain.

Role tags are missing from the ALTO

Role classification is off by default, and body lines are never tagged. See line roles.

Running out of memory

The process is killed during a batch

Each worker needs about 1.3 GiB. Drop to one worker and release memory between pages:

TUZKAOCR_CPU_MEM_ARENA=false tuzkaocr input/ --batch --workers 1

See memory.

Idle memory stays high after a batch finishes

By design; set TUZKAOCR_CPU_MEM_ARENA=false — see memory.

Service errors

503 with a Retry-After header

The queue is full (TUZKAOCR_MAX_QUEUE). Retry after the given delay; raise throughput with TUZKAOCR_PAGE_WORKERS.

413 on upload

The request body exceeds TUZKAOCR_MAX_UPLOAD_MB (default 256). Raise it, or send a smaller derivative.

422, or a job that fails with a decode error

The image could not be decoded or exceeds TUZKAOCR_MAX_IMAGE_PIXELS (default 300 megapixels). The message is in the status response's error field.

404 from status for a job that definitely existed

The job aged out (TUZKAOCR_MAX_JOB_AGE_HOURS) or the server restarted. The result endpoint may still serve the file.

Permission denied writing to results/

Compose runs the container as 1000:1000:

TUZKAOCR_RUN_UID=$(id -u) TUZKAOCR_RUN_GID=$(id -g) docker compose up -d cpu

The server exits at startup with a configuration error

The message names every invalid setting. Note that booleans accept only 1, true and yes.

GPU is not being used

The pinned onnxruntime is CPU-only. Use the GPU image.

Custom domain packs

A pack is missing from --list-domains

Check that the .tpack or pack folder is directly inside TUZKAOCR_DOMAINS_DIR. Non-default packs with invalid manifests, checksums, or version requirements are skipped with a warning. Run python cli.py --check-domains for the full validation report.

sha256 mismatch for <file>

The file differs from the checksum in domain.json. Re-copy the complete pack from its provider rather than editing one model file in place.

unknown setting key '<key>' or an invalid setting value

Remove the unsupported setting or correct its value, then ask the pack provider to rebuild the archive. Pack settings use the same ranges as the corresponding TUZKAOCR_* setting.

requires_tuzkaocr is unsupported or does not match this version

Use a pack built for the installed core version, or install a compatible TuzkaOCR release.

unsafe zip member or a .tpack size-limit error

The archive contains a path outside its root, nested folders, or more than the allowed uncompressed size. Ask the provider for a corrected archive.

model ... expects N classes, vocab ... covers M

The recognizer and vocabulary do not match. Pass the vocabulary shipped with that model; every custom recognizer needs its matching vocabulary.

Unknown domain in the CLI or API

Run python cli.py --list-domains or query /api/v1/models; use a listed built-in or pack name. An explicit print selection bypasses a pack default.