---
title: "Troubleshooting"
description: "Problems and error messages of LumiScan Text Reader - empty or wrong readings, slow reading, status codes -1, -2, -3 and -7, language models, the image stream and settings lost after a restart."
product: "LumiScan Text Reader"
component: "lumiscan-text-reader"
version: "1.1.0"
display_version: "1.1.0.6"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html"
---

# Troubleshooting – LumiScan Text Reader

This page starts with the general checks that apply to every problem. The problems follow, grouped into reading results, status codes, language models, the image stream, and modules and settings. Do the general checks first, then find your symptom.

All addresses are relative to `hdvisionsystems/lumiscan-text-reader/`.

## General checks {#general-checks}

- Read `output/status-code` and `output/status-text` of the operation, for a reading `<module>/read-text/output/status-code` and `<module>/read-text/output/status-text`. The sign of the status code tells you whether it worked: greater than 0 is success, `0` means the operation has not run since the application started, less than 0 means it failed and produced nothing. The codes are listed in [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/execution-status.html).
- A failed write to `execute` answers with a status code only (over REST, a bare `400`). Read `output/status-text` afterwards: it starts with `ok:` or `error:` and gives the reason.
- Read the application log. On ctrlX OS, read it in the ctrlX Logbook or with `journalctl`; on a PC, in the application’s console output. The log has the same text as `output/status-text`; when several inputs are wrong, each one gets its own warning line.
- Check what the reading actually used: `language`, `engine` and `layout` in `output/result`. They are not always the inputs you set.
- Check that the image source runs on the **same device** as the Text Reader - the same ctrlX CORE or ctrlX IPC, or the same PC. Remote Data Layer access is not supported.
- Check the image quality. No setting recovers text the camera did not capture: characters at least 20 pixels tall (30 or more for small or noisy print), good contrast, text in focus and not glared out, text roughly upright unless you use an orientation-detecting layout. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/requirements.html).
- Check the licence. On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is written to the system log. A module that no licence on the device covers is refused with status `-11`. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/requirements.html#licence).
- Problems that all LumiScan apps share - an app or module missing from the tree, a node that is "not found", a method call that is refused, a stream that delivers nothing - are described in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html) of the LumiScan Keryx manual.

## Reading results

### Problem: Status code 1, but no words {#faq-empty-reading}

**Symptoms**

`output/status-code` is `1` (OK), but `output/result` has `word_count` `0`.

**Possible causes**

- 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](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-empty-colour-image).

**Diagnostic procedure**

1. Check `text` in `output/result`. If `text` is not empty but `word_count` is `0`, the words were filtered: compare the word scores with `min_score` in the result, which is the threshold that was applied.
2. Check that the marking is inside `input/crop/startX`, `input/crop/startY`, `input/crop/width` and `input/crop/height`. `image_width` and `image_height` in the result show the region that was read.
3. Check in the camera image that the marking is in focus and the right way up.
4. If the image is a colour image and you can see the text, continue with [Problem: The reading is empty although the text is clearly visible in a colour image](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-empty-colour-image).

**Resolution**

- **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](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/reading-accurately.html), step 5.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with `output/status-text`, the content of `output/result` and the values of the `read-text/input/` nodes.

### Problem: The reading is empty although the text is clearly visible in a colour image {#faq-empty-colour-image}

**Symptoms**

A colour frame in which a photograph or other colourful scenery shares the image with the text comes back with no words at all, while `output/status-code` reports success (`1`). The text is not garbled - the reading is empty.

**Possible causes**

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

**Diagnostic procedure**

1. Check that `pixel-type` of the image node is a colour format (for example `RGB8` or `BGR8`).
2. Check `input/preprocess`. Its default is `NONE`.
3. Check whether a rectangle can separate the text from the scenery.

**Resolution**

- **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):
  1. Set `input/preprocess` to `GRAYSCALE` and read again.
  2. Only if `GRAYSCALE` did not help, try `BINARIZE_OTSU`.

Neither setting invents text: on a frame with no text in it, all three settings return nothing.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with `output/status-text`, the values of `input/crop` and `input/preprocess`, and the pixel format of the image.

### Problem: Digits are read as letters (O for 0, S for 5) {#faq-digits-letters}

**Symptoms**

Characters are substituted between character classes, for example `O` for `0` or `S` for `5`. Other typical substitutions are `I`/`1`/`l`, `B`/`8` and `Z`/`2`.

**Possible causes**

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

**Diagnostic procedure**

1. Read `input/characters/mode`, `input/characters/allow` and `input/characters/deny`. Expected for a restricted marking: a mode other than `ALL_SYMBOLS`.

**Resolution**

- **If the character set is not restricted:** set `input/characters/mode` to match the marking:
  - numeric part or batch number: `DIGITS`;
  - upper-case alphanumeric code: `UPPERCASE_LETTERS` with `input/characters/allow` = `0123456789`;
  - date code with separators: `DIGITS` with `allow` = `/-.`;
  - fixed alphabet: `CUSTOM` with `allow` set to exactly that alphabet.

An empty character set - `CUSTOM` with an empty `allow`, or a `deny` that removes everything the mode selected - is refused with status code `-2`.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the values of `input/characters/mode`, `allow` and `deny`, and `output/result`.

### Problem: The reading contains extra words from the background {#faq-extra-words}

**Symptoms**

`output/result` contains words that are not part of the marking, picked out of the background - edges of the part, shadows, the conveyor. These words usually have a low `words[].score`.

**Possible causes**

- `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.

**Diagnostic procedure**

1. Check `input/crop`, and `image_width` and `image_height` in the result: they show the region that was read.
2. Check `layout` in the result.
3. Check the `words[].score` of the extra words and `min_score` in the result. Spurious words usually sit below 0.5.

**Resolution**

- **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:**
  1. Run known-good parts with `min-score` at `0`.
  2. Note `mean_score` and the individual word scores in the result.
  3. Set `input/min-score` between the noise (usually below 0.5) and the correct readings (usually well above 0.8), closer to the correct readings.

`min-score` filters `words[]` only; `text` is always the engine’s full output. Check `word_count` rather than `text` when you need to know whether the reading was good.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with `output/result` and the values of `input/crop`, `input/layout` and `input/min-score`.

### Problem: Dot-matrix or laser-etched marking reads badly {#faq-dot-matrix}

**Symptoms**

A dot-matrix or laser-etched marking is read badly, while printed text reads well.

**Possible causes**

- These markings defeat the `LSTM` engine more often than printed text.
- Lighting, contrast or focus are poor. No setting fixes them.

**Diagnostic procedure**

1. Check `engine` in the result: the engine that was actually used.
2. Check the image against the image quality rules in [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/requirements.html): character height, contrast, focus and glare.

**Resolution**

- **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.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with `output/result` and the value of `input/engine`.

### Problem: Reading is too slow {#faq-reading-too-slow}

**Symptoms**

The call to `read-text/execute` takes too long for your cycle. Reading is synchronous: the call returns when the read has finished.

**Possible causes**

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

**Diagnostic procedure**

1. Check `input/crop`, and `image_width` and `image_height` in the result.
2. Check `layout` in the result.

**Resolution**

- **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.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the values of `input/crop` and `input/layout` and the image size.

## Status codes

### Problem: Status code -2 (a setting is unusable) {#faq-status-minus-2}

**Symptoms**

`output/status-code` is `-2` (Invalid input). `output/status-text` starts with `error:` and names every offending node and what it expected, for example `min-score must be between 0 and 1, got 1.5` or `error: crop/startX + crop/width (100 + 900 = 1000) exceeds the image width 640`.

**Possible causes**

- 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 …")](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-osd-beside-language).
- 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.

**Diagnostic procedure**

1. Read `output/status-text`. A run checks every setting and reports **all** the problems at once.
2. Read the application log: each wrong input has its own warning line.

**Resolution**

- **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](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/datalayer-reference.html).
- **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](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/lumiscan-text-reader/language-models.html).
- **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`.

Then run the operation again and check that `output/status-code` is `1`.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the full `output/status-text` and the values of the `read-text/input/` nodes.

### Problem: Status code -3 (image cannot be read) {#faq-status-minus-3}

**Symptoms**

`output/status-code` is `-3` (Image read failed), and the result is empty.

**Possible causes**

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

**Diagnostic procedure**

1. Check `input/input-image-address`, for example `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
2. Check that the image node has the children `data`, `width`, `height` and `pixel-type`, and that `data` holds pixel data.
3. Check that `pixel-type` is one of `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` or `BayerRG12`.
4. Check that the source application runs on the same device - the same ctrlX CORE or ctrlX IPC, or the same PC - and delivers images.
5. Read `output/status-text` for the reason.

**Resolution**

- **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.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with `input/input-image-address`, `output/status-text` and the `pixel-type`, `width` and `height` of the image node.

### Problem: Status code -7 (OCR engine could not start) {#faq-status-minus-7}

**Symptoms**

`output/status-code` is `-7` (Algorithm failed). The result is empty, and the reason is in `output/status-text`.

**Possible causes**

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

**Diagnostic procedure**

1. Read `output/status-text` for the reason.
2. Check that `system/languages` is not empty. `system/languages` is refreshed only at startup, by `set-tessdata-dir` and by `refresh-languages`: write to `system/refresh-languages/execute` to update it.
3. Check `system/tessdata-dirs`: every directory searched, in order.
4. Check whether a model upload was in progress when the read failed.

**Resolution**

- **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.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the full `output/status-text` and the values of `system/tessdata-dir`, `system/tessdata-dirs` and `system/languages`.

## Language models

### Problem: A reading with AUTO_OSD or SPARSE_OSD is refused ("also needs osd.traineddata beside …") {#faq-osd-beside-language}

**Symptoms**

A reading is refused with `output/status-code` `-2` and the message

```
error: invalid input: layout AUTO_OSD also needs osd.traineddata beside 'deu.traineddata' in '<tessdata-dir>'; copy it from '<shipped dir>', or choose a layout that does not detect orientation
```

**Possible causes**

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

**Diagnostic procedure**

1. Check `input/layout`. Expected for this message: `AUTO_OSD` or `SPARSE_OSD`.
2. Check whether the directory named in the message holds `osd.traineddata` beside the language model.

**Resolution**

- **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`.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the full message and the values of `system/tessdata-dirs` and `system/languages`.

### Problem: An uploaded model does not appear on system/languages {#faq-languages-list}

**Symptoms**

You uploaded a `.traineddata` file, but its language code is not listed on `system/languages`.

**Possible causes**

- `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.

**Diagnostic procedure**

1. Check that the file is in the directory named on `system/tessdata-dir`.
2. Check that the file name is unchanged, exactly as the Tesseract project publishes it (for example `deu.traineddata`, `chi_sim.traineddata`).

**Resolution**

- **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.

`osd` appears in the list but is not a language: setting `input/language` to `osd` does not read anything.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the values of `system/tessdata-dir`, `system/tessdata-dirs` and `system/languages` and the name of the uploaded file.

### Problem: The text is read in another language than input/language {#ts-wrong-language}

**Symptoms**

`language` in `output/result` is not the language set in `input/language`, and `output/status-text` contains a `NOTE`, for example

```
ok: 4 word(s), mean score 0.91 (eng, SINGLE_BLOCK) - NOTE: language 'deu' is not installed, read with 'eng' instead
```

**Possible causes**

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

**Diagnostic procedure**

1. Compare `language` in `output/result` with `input/language`.
2. Read `output/status-text` for the `NOTE`.
3. Check that the model file is still in its directory (see `system/tessdata-dirs`).

**Resolution**

- **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`.

Read `language` in `output/result`, not `input/language`, when you need to know how a result was produced. If the language is not installed at all, the reading is refused with `-2`, see [Problem: Status code -2 (a setting is unusable)](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-status-minus-2). For the image stream, see [Problem: A stream frame fails with "the frame was read with 'eng' instead and its result dropped"](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#faq-stream-language-dropped).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with `output/status-text`, `output/result` and the values of `input/language`, `system/tessdata-dirs` and `system/languages`.

## Image stream

### Problem: read-text answers -1 (busy) while the stream runs {#faq-stream-busy}

**Symptoms**

While the image stream (experimental) runs, a call of `read-text/execute` is refused:

- `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.

`system/remove-module` also answers busy (`-1`) while a frame of that module is read.

**Possible causes**

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

**Diagnostic procedure**

1. Read `control/subscribe/output/stream/active` of the module. `true` means the stream runs.

**Resolution**

- **If you need `read-text` while the stream runs:** call `read-text/execute` again, or stop the stream first:
  1. Set `control/subscribe/input/enable` to `false` and write to `control/subscribe/execute`. The frame being read is finished first.
  2. Check that `control/subscribe/output/stream/active` is `false`.
  3. Call `read-text/execute`.
- **If you want to remove the module:** stop the stream first, then call `system/remove-module/execute`.

Other modules are not affected: each module has its own lock, its own engine and its own stream.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the values of `control/subscribe/output/stream/active` and the counters under `control/subscribe/output/stream/statistics/`.

### Problem: A stream frame fails with "the frame was read with 'eng' instead and its result dropped" {#faq-stream-language-dropped}

**Symptoms**

A frame of the image stream (experimental) gives no result. `control/subscribe/output/stream/statistics/failed-frames` grows, and `control/subscribe/output/stream/last-failure` and the log say, for example:

```
a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: language 'deu' is no longer installed; the frame was read with 'eng' instead and its result dropped
```

**Possible causes**

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

**Diagnostic procedure**

1. Read `control/subscribe/output/stream/last-failure`.
2. Check `control/subscribe/output/stream/statistics/failed-frames`.
3. Check that the model file for `input/language` is still in its directory (see `system/tessdata-dirs`).

**Resolution**

- **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.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with `control/subscribe/output/stream/last-failure`, the counters under `control/subscribe/output/stream/statistics/` and the values of `input/language` and `system/tessdata-dirs`.

## Modules and settings

### Problem: My settings or modules are gone after a restart {#faq-settings-lost}

**Symptoms**

After a restart of the application, a module is missing from `system/modules`, a module is back with its default inputs, or a module that streamed before does not stream.

**Possible causes**

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

**Diagnostic procedure**

1. Read `system/modules`.
2. Check the log for a module file reported as unreadable, or for skipped settings.
3. Check that `<module-id>.json` exists in the configuration directory: on ctrlX OS `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-text-reader`; on a PC (Windows) `%APP_RESOURCE_DIR%\etc\lumiscan-text-reader`, or without `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-text-read\etc\lumiscan-text-reader`.

**Resolution**

- **If the module’s settings were not saved:**
  1. Set `system/save-module-inputs/input/module-id`, for example `module-1`.
  2. Write to `system/save-module-inputs/execute`.
  3. Check that `system/save-module-inputs/output/status-code` is `1`.
- **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.

A directory chosen with `system/set-tessdata-dir` is saved automatically.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-text-reader/1.1.0/troubleshooting.html#support-information) to support, together with the content of `system/modules`, the files in the configuration directory and the log of the start.

## Information for support {#support-information}

If a problem persists, send the following information to support:

- The version of LumiScan Text Reader.
- The platform: ctrlX OS on a ctrlX CORE or ctrlX IPC, with the ctrlX OS version; or a PC with Windows 11 or Ubuntu 24.04 and LumiScan Keryx.
- The application log: on ctrlX OS from the ctrlX Logbook or `journalctl`, on a PC the application’s console output.
- The date and time of the error.
- The Data Layer status: which Data Layer you use (ctrlX Data Layer or LumiScan Keryx; on a PC, the Data Layer address), the `output/status-code` and `output/status-text` of the operation that failed and, for a refused write, the result of the write. For the image stream, also `control/subscribe/output/stream/last-failure` and the counters under `control/subscribe/output/stream/statistics/`.
- The configuration: the values of the `read-text/input/` nodes, `system/modules`, `system/tessdata-dir`, `system/tessdata-dirs` and `system/languages`, and the files in the configuration directory (the module files `<module-id>.json`).

Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905. For licences, contact [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).