Troubleshooting

Nothing readable is in the image: an empty carrier, a part turned the wrong way, or a label out of frame. This is the normal answer, not an error.

The marking is outside the crop. A marking that drifts outside the crop reads as nothing.

The marking is not in focus, or not the right way up.

input/min-score filters out every word. words[] is filtered by min-score; text is not.

A colour image in which a photograph or other colourful scenery shares the frame with the text, see Problem: The reading is empty although the text is clearly visible in a colour image.

If there is no text in the image: this is a valid result. Branch on word_count, not on the status code, to decide whether a part carried text.

If the marking is outside the crop: make the crop large enough to cover the whole range the part can occupy, then read again.

If the marking is out of focus or not the right way up: correct the camera set-up. For text whose orientation really varies, use an orientation-detecting layout (AUTO_OSD or SPARSE_OSD).

If input/min-score filters out every word: set the threshold again as described in Reading Accurately, step 5.

The engine reduces a colour image before reading it, and with colourful scenery in the frame this loses the text. The size of the text is not the cause. No input/layout and no input/engine rescues this case.

If a rectangle can separate the text from the scenery: crop to the text first with input/crop. Cropping fixes this case in colour.

If the text and the scenery cannot be separated by a rectangle (for example a label on a patterned part, or a screen photographed whole):

An unfamiliar character is substituted rather than rejected, and the default input/characters/mode ALL_SYMBOLS permits every class.

If the character set is not restricted: set input/characters/mode to match the marking:

input/crop is loose or not set. All zero reads the whole image.

input/layout looks for more structure than the marking has.

input/min-score is 0 (the default), which reports everything.

If the crop is loose: tighten input/crop around where the text will be. This is the most effective setting, and it also makes reading faster.

If the layout does not match: set input/layout to the marking, for example SINGLE_LINE for one line of print.

If input/min-score is too low:

These markings defeat the LSTM engine more often than printed text.

Lighting, contrast or focus are poor. No setting fixes them.

If the engine is the cause: set input/engine to LEGACY and compare the readings.

If the image quality is poor: fix the lighting and the focus.

The engine is given too much image. Reading time is driven mostly by how much image the engine is given.

The AUTO_OSD or SPARSE_OSD layout is used. These layouts load a second model and work out the orientation first.

If the engine is given too much image: tighten input/crop around the label. A tight crop is both faster and more accurate than the whole frame.

If an _OSD layout is used: use a layout without orientation detection, unless the orientation really varies.

A required node is left empty.

An unknown value in input/engine, input/layout, input/preprocess or input/characters/mode.

A value out of range, for example input/min-score outside 0 to 1.

An empty character set: CUSTOM with an empty allow, or a deny that removes everything the mode selected.

A language with no model installed. The message names every directory searched and what is available, for example error: invalid input: language 'fra' has no fra.traineddata in any model directory ('<tessdata-dir>', '<shipped dir>'); available: eng, osd. Upload fra.traineddata to '<tessdata-dir>' - the file name is the language code.

A layout with orientation detection without osd.traineddata beside the language model, see Problem: A reading with AUTO_OSD or SPARSE_OSD is refused ("also needs osd.traineddata beside …​").

A crop that does not fit the image. It is refused, not trimmed to fit.

An image address that points at this application itself.

For system/set-tessdata-dir: input/tessdata-dir is empty.

If a value is unknown, out of range or empty: correct each node named in output/status-text. The accepted values are listed in Data Layer Reference.

If the character set is empty: set input/characters/allow, or remove characters from input/characters/deny, so that the set is not empty.

If the language has no model: upload <language>.traineddata into the directory system/tessdata-dir names, without renaming it, or set input/language to a code on system/languages. See Language Models.

If the crop does not fit: change input/crop so that startX + width and startY + height are inside the image.

If the image address points at this application: set input/input-image-address to the image node of the camera application.

If input/tessdata-dir is empty: write a directory to system/set-tessdata-dir/input/tessdata-dir, then write to system/set-tessdata-dir/execute.

A wrong image address in input/input-image-address. This is almost always the cause.

The source application is not running on the same device, or it has not captured an image.

The image node is missing, empty or inconsistent.

The image uses an unsupported pixel format.

If the address is wrong: correct input/input-image-address and read again.

If the source application is not running or has not captured an image: start it on the same device, capture an image, then read again.

If the image node is empty or inconsistent: capture a new image with the source application, then read again.

If the pixel format is not supported: use an image source that delivers one of the supported pixel formats.

The OCR engine could not start, usually because of the language model directory.

A language model could not be loaded, for example a model whose upload is still in progress. This happens when a read follows right after a model was replaced.

If an upload was in progress: read again once the upload has completed. That read loads the new model.

If the reason names the language model directory: check the directories on system/tessdata-dirs against the reason in output/status-text. If you changed the upload directory with system/set-tessdata-dir, check that it is the directory that holds your models.

The AUTO_OSD and SPARSE_OSD layouts need osd.traineddata in the same directory as the language model, not merely somewhere on the search path. Tesseract resolves one directory per run. For example, deu.traineddata was uploaded on its own.

If you need orientation detection: upload osd.traineddata into the same directory as your model. The message names the shipped directory to copy it from. Then read again.

If you do not need orientation detection: use a layout that does not detect orientation, such as the default SINGLE_BLOCK.

system/languages is a listing. It is refreshed only at startup, by set-tessdata-dir and by refresh-languages.

The file is not in the directory system/tessdata-dir names, or it was renamed. The file name is the language code.

If the listing is not refreshed: write to system/refresh-languages/execute, then read system/languages. You do not need this in order to read: an uploaded model is usable on the very next read-text.

If the file is in another directory or was renamed: upload it again, without renaming, into the directory system/tessdata-dir names.

The language model disappeared between the language check and the read - someone pulled the USB stick, for example. The engine then reads with eng.

If the model disappeared: make the model available again in its directory, for example insert the USB stick again or upload the model again. A model you upload is usable on the very next read-text. Then read again and check language in output/result.

output/status-code is -1 (Busy);

the write answers DL_TOO_MANY_OPERATIONS (ctrlX OS) or TooManyOperations (PC);

nothing is done, and output/result keeps its value.

The stream and read-text share the module’s one recognition engine and never run at the same time on one module. With a camera streaming, this happens often.

If you need read-text while the stream runs: call read-text/execute again, or stop the stream first:

If you want to remove the module: stop the stream first, then call system/remove-module/execute.

The language model disappeared between the language check and the read, so the engine read with eng. read-text publishes such a reading with a NOTE in its status-text, but the stream drops it, because its settings hash names the model that was asked for.

If the model disappeared: make the model for input/language available in its directory again. A model you upload is used from the next frame on. Keep it available while the stream runs - do not remove the USB stick it is on, for example.

The module list was not saved with system/save-current-modules. Nothing survives a restart until it is saved; the module list and each module’s settings are saved separately.

The module’s settings were not saved with system/save-module-inputs.

The image stream’s mode and source are saved by control/subscribe/execute in the module’s <module-id>.json, but they come back only if the module list is saved too.

<module-id>.json contains comments. The module’s inputs are then not restored at start; the log reports the file as unreadable.

A setting whose node no longer exists after a software update is skipped, with a log entry.

If the module’s settings were not saved:

If the module list was not saved: write to system/save-current-modules/execute. The stream mode and source of a module come back after a restart only if the module list is saved too.

If <module-id>.json contains comments: remove the comments from the file. Changes made to the file by hand take effect at the next start.