---
title: "Troubleshooting"
description: "Problems and error messages of LumiScan Template Finder step by step - status codes, search results, templates, the image stream, modules, settings and licensing."
product: "LumiScan Template Finder"
component: "lumiscan-template-finder"
version: "1.1.0"
display_version: "1.1.0.7"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html"
---

# Troubleshooting – LumiScan Template Finder

This page describes problems and error messages of LumiScan Template Finder, grouped by category. Start with the [general checks](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#general-checks), then find your symptom below: each problem lists its symptoms, the possible causes, a diagnostic procedure and the resolution. Problems of the Data Layer itself are described in [Data Layer troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html), licence problems in [Licensing troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/troubleshooting.html).

## General checks {#general-checks}

1. **Check the status code.** Read `output/status-code` of the operation that failed. Expected: `1`. A value greater than 0 means success, `0` means the operation has not run since the application started, and a value less than 0 means it failed and produced nothing. The codes are listed in [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/execution-status.html).
2. **Read the status text.** Read `output/status-text` of the same operation. It starts with `ok:` or `error:` and names every invalid input and the value it holds. A failed write to `execute` answers with a status code only (over REST, a bare `400`), so the reason is only on `output/status-text`.
3. **Read the application log.** It holds the same text, with one warning line for each invalid input: on ctrlX OS in the ctrlX Logbook or with `journalctl`, on a PC in the application’s console output. How much is logged is set with `logLevel` in the `system` block of `lumiscan-template-finder.json` (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` or `OFF`); without the key, the application logs at `DEBUG`. The level is read once, at startup, so restart the application after you change it. `TRACE` is what to set before you reproduce a problem for a support report. See [Template Storage](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/template-storage.html).
4. **Check the image source.** The camera application, normally LumiScan Cam Driver, must run on the **same device** - the same ctrlX CORE or ctrlX IPC, or the same PC - and must have captured an image. Remote Data Layer access is not supported. Expected: the node named in `input/input-image-address` provides `data`, `width`, `height` and `pixel-type`.
5. **Check the order of the calls.** A module runs one operation at a time, and every run clears its outputs as it starts. Expected: your program waits for `execute` to return, reads the outputs, and only then triggers the next run.
6. **Check the licence (ctrlX OS).** Expected: the application keeps running after it starts. Without a licence it shuts down shortly after starting; see [Problem: The application stops shortly after starting](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-app-stops-after-start).

The configuration directory holds `lumiscan-template-finder.json`, the module files `<module-id>.json`, the `templates` folder and `settings-history/`:

| Platform | Configuration directory |
| --- | --- |
| ctrlX OS | `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-template-finder`, part of the active solution |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-template-finder`; without `APP_RESOURCE_DIR`, `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-templ-find\etc\lumiscan-template-finder` |

## Status codes and error messages {#ts-status-codes}

### Problem: Status code `-1` (busy) {#faq-busy-while-streaming}

**Symptoms**

`output/status-code` of `find-template` is `-1`. The write to `execute` answers `TooManyOperations` (ctrlX: `DL_TOO_MANY_OPERATIONS`). Nothing was done, and `output/result` keeps its value. With a camera streaming, this happens often. `system/remove-module` can answer `-1` (busy) as well.

**Possible causes**

- Another operation of the same module was still running. A second call is not queued; it returns at once and does nothing.
- The module’s image stream is searching a frame. The stream and `find-template` never run at the same time on one module.

**Diagnostic procedure**

1. Check in your program whether it writes to `execute` of the same module again before the previous write has returned. Expected: one call per module at a time.
2. Read `<module-id>/control/subscribe/output/stream/active`. `true` means that the stream of this module runs.

**Resolution**

- **If another operation was still running:** wait for the running `execute` to return, then call the method again. The lock is per module, so other modules are not held up.

- **If the stream of the module runs:**

  a. Stop the stream before you call the method: set `control/subscribe/input/enable` to `false` and write to `control/subscribe/execute`. Or call the method again.

  b. To use the results of the stream instead, switch on `control/subscribe/input/keep-latest-output` and read `find-template/output/result`.

- **If `system/remove-module` answers busy:** stop the stream of the module first. Removing a module stops its stream.

See [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/execute-a-method.html) and [find-template while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#while-streaming).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the module id, the answer of the write to `execute` and the value of `control/subscribe/output/stream/active`.

### Problem: Status code `-2` (invalid input) {#faq-status-minus-2}

**Symptoms**

`output/status-code` is `-2`. `output/status-text` starts with `error:` and names every offending input and the value it holds, for example `min-scale must be > 0, got 0`. Each one is also logged as a warning.

**Possible causes**

- A required input is empty: `input/input-image-address` or `input/template-name`.
- The match mode is misspelled. `input/match-mode` accepts `TM_SQDIFF`, `TM_SQDIFF_NORMED`, `TM_CCORR`, `TM_CCORR_NORMED`, `TM_CCOEFF` and `TM_CCOEFF_NORMED`.
- A search parameter is out of range, for example `input/scale/min-scale` or `input/rotation/step-rot` not greater than 0, or a rotation outside 0 to 360.
- The image address points at this application itself.
- A folder or file name is an absolute path, such as `/tmp/templates`, or a path that leads outside the configuration directory, such as `../../etc`.

**Diagnostic procedure**

1. Read `output/status-text` of the operation. Expected: it names each offending input and its value.
2. Read the application log. Each offending input is logged as a warning.

**Resolution**

- **If a required input is empty:** set it. `input/template-name` takes an entry of `system/templates`.
- **If the match mode is misspelled:** write one of the accepted names to `input/match-mode`.
- **If a search parameter is out of range:** correct it, see [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/tuning-the-search.html).
- **If the image address points at this application:** set `input/input-image-address` to the image node of the camera application, for example `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
- **If a path is absolute or leaves the configuration directory:** give it relative to the configuration directory. A path that stays inside is fine even if it contains `..`.

Then run the operation again. Expected: `output/status-code` is `1`. See [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/execution-status.html) and [Template Storage](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/template-storage.html).

**If the problem persists**

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

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

**Symptoms**

`output/status-code` of `find-template` or `system/create-template` is `-3`.

**Possible causes**

- The camera application is not running, or it runs on another device.
- The camera application has not captured an image yet.
- The address in `input/input-image-address` is wrong.
- The image node at the address is missing, empty or inconsistent.
- The image uses an unsupported pixel format. Supported are `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `BayerGR8`, `BayerGR12`, `BayerRG8` and `BayerRG12`.

**Diagnostic procedure**

1. Check that the camera application, normally LumiScan Cam Driver, runs on the same device. Expected: it runs on the same ctrlX CORE or ctrlX IPC, or on the same PC.
2. Compare `input/input-image-address` with the address of the camera’s image node, for example `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. Expected: identical. `system/create-template` and `find-template` each have their own address node.
3. Read `width`, `height` and `pixel-type` of the image node. Expected: values greater than 0, and a `pixel-type` from the list above.

**Resolution**

- **If the camera application is not running:** start it on the same device and capture an image.
- **If no image has been captured yet:** capture an image in the camera application.
- **If the address is wrong:** correct `input/input-image-address`.
- **If the pixel format is not supported:** use one of the supported pixel formats, see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/requirements.html).

Then run the operation again. Expected: `output/status-code` is `1`.

**If the problem persists**

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

### Problem: Status code `-4` (source not found) {#faq-status-minus-4}

**Symptoms**

`output/status-code` of `find-template` is `-4`. `output/status-text` names a directory or a file.

**Possible causes**

- The message names a directory: the template folder does not exist. The default `templates` is created at startup, so either it was deleted or the folder name is wrong.
- The message names a file: the folder exists but holds no such file.
- The file is there but is not found: it is in a different folder from the one in use. All modules share one template folder.

**Diagnostic procedure**

1. Read `output/status-text`. Expected: it names a directory or a file.
2. Compare `input/template-name` with `system/templates`. Expected: the name is listed, spelled the same way.
3. Read `system/template-dir`. Expected: it names the folder that holds the file.

**Resolution**

- **If the folder does not exist:** switch to an existing folder with `system/set-template-dir`, or correct its name. The folder must already exist; it is not created for you.
- **If the folder holds no such file:** correct the spelling of `input/template-name`, or create the template with `system/create-template`.
- **If the file is in another folder:** move the file into the folder `system/template-dir` names, or switch with `system/set-template-dir`.

Then run `find-template` again. Expected: `output/status-code` is `1`. See [Template Storage](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/template-storage.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the content of `output/status-text`, `input/template-name`, `system/template-dir` and `system/templates`.

### Problem: The crop region does not fit the image {#ts-crop-does-not-fit}

**Symptoms**

`system/create-template` answers status `-5` (invalid crop region), and `output/status-text` names the actual image size. For `find-template`, `output/status-text` names the input and the limit it broke, for example:

```
crop/startX + crop/width (100 + 541 = 641) exceeds the image width 640
```

In the image stream, the frame fails, and `control/subscribe/output/stream/last-failure` names a crop region that does not fit the frame.

**Possible causes**

- The region reaches past an edge of the image. A region reaching past an edge is refused, not trimmed.
- For `find-template`, the region is smaller than the template. This is refused with status `-5`.
- For `system/create-template`, `input/crop/width` or `input/crop/height` is 0. Both must be greater than 0.

**Diagnostic procedure**

1. Read the image size from the message, or `width` and `height` of the image node.
2. Add `input/crop/startX` and `input/crop/width`, and `input/crop/startY` and `input/crop/height`. Expected: the sums are not larger than the image width and the image height.
3. For `find-template`, compare the region with the size of the template. Expected: the region is at least as large as the template.

**Resolution**

- **If the region reaches past an edge:** correct `input/crop/startX`, `startY`, `width` or `height`, so that the region fits the image. A zero width or height reaches the right or bottom edge.
- **If the region is smaller than the template:** widen the region.
- **If width or height is 0 (`create-template`):** set both to the size of the region, greater than 0.

Then run the operation again. Expected: `output/status-code` is `1`. See [Finding a Template](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/finding-a-template.html) and [Creating a Template](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/creating-a-template.html).

**If the problem persists**

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

### Problem: Status code `-6` (write failed) {#ts-status-minus-6}

**Symptoms**

`output/status-code` of `system/save-module-inputs` or `system/create-template` is `-6`.

**Possible causes**

- A file could not be written - usually a permission problem or a full disk.
- The configuration directory is not writable. The same problem is reported in the log at startup.

**Diagnostic procedure**

1. Read `output/status-text` of the operation. Expected: it names the file that could not be written.
2. Read the application log of the start. Expected: no message that the configuration directory is not writable.
3. Check the configuration directory (see [General checks](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#general-checks)). Expected: it exists and the application can write to it.

**Resolution**

- **If the configuration directory is not writable:** make it writable for the application.
- **If the disk is full:** free disk space on the device.

Then run the operation again. Expected: `output/status-code` is `1`.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the content of `output/status-text` and the log of the start.

## Search results {#ts-results}

### Problem: The result is empty although the status code is `1` {#ts-empty-result}

**Symptoms**

`output/status-code` of `find-template` is `1`, but `matches` in `output/result` is empty, and `best_score` is `0.0`.

**Possible causes**

An empty `matches` list with status code `1` means that the search ran correctly and found nothing. That is a normal result: the part is not there, or not similar enough to pass the threshold. If a part that is there is not found:

- The template was cut from the wrong region or the wrong image, see [Problem: The template is not found even in the image it was cut from](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-not-found-in-own-image).
- The part is rotated or at another distance than in the template, see [Problem: The part is not found when it is rotated or at a different distance](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-rotation-scale).
- `input/crop` excludes the part.
- The template touches the edge of the image. Such a template cannot be found near the opposite edge, because the template must fit entirely inside the searched image.
- Background that changes from part to part is inside the template; it lowers every score.

**Diagnostic procedure**

1. Read `output/status-code`. Expected: `1`. If it is negative, the run failed: read `output/status-text` and see the entries under [Status codes and error messages](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#ts-status-codes).
2. Search the image the template was cut from. Expected: one match at the centre of the region you specified, with a confidence close to 1.
3. Compare the orientation and the size of the part in the image with the template.
4. Read the four `input/crop/` values. Expected: all `0` (the whole image), or a region that contains the part.
5. Read `match_thresh` in `output/result`: the threshold that was applied (default `0.9`).

**Resolution**

- **If the template is not found in its own image:** follow [Problem: The template is not found even in the image it was cut from](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-not-found-in-own-image).
- **If the part is rotated or at another distance:** follow [Problem: The part is not found when it is rotated or at a different distance](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-rotation-scale).
- **If the crop excludes the part:** widen the region, or set all four `input/crop/` values to `0`.
- **If the template touches the image border or holds changing background:** create the template again from a region that stays away from the image border, includes what identifies the part and excludes what varies. See [Creating a Template](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/creating-a-template.html).
- **If the part was not in the image:** the result is correct; nothing needs to be changed.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with `input/template-name`, the template file and `output/result`.

### Problem: The template is not found even in the image it was cut from {#faq-not-found-in-own-image}

**Symptoms**

A search in the very image the template was cut from does not report the match at the centre of the region you specified, with a confidence close to 1.

**Possible causes**

- The region given when the template was created is wrong.
- The image address is wrong: the template was cut from another image than the one searched. `system/create-template/input/input-image-address` and `<module>/find-template/input/input-image-address` are separate nodes.

The search parameters are not the cause, and no amount of tuning fixes it.

**Diagnostic procedure**

1. Compare `system/create-template/input/input-image-address` with `<module>/find-template/input/input-image-address`. Expected: the same image node.
2. Read the four `system/create-template/input/crop/` values. Expected: a region that contains the part in that image.
3. Read `system/create-template/output/template-path`. Expected: the file you search for, for example `templates/screw.png`.

**Resolution**

- Correct `input/input-image-address` and the crop region, then create the template again. Searched in the same image, it must be found exactly at the centre of the region you specified - (195, 250) for a region starting at (100, 200) that is 190 x 100 pixels - with a confidence close to 1.

See [Creating a Template](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/creating-a-template.html) and [How To: Match a Part from a Camera Image](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/how-tos/match-a-part-from-a-camera-image.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the inputs of `system/create-template`, the template file and `output/result`.

### Problem: The part is not found when it is rotated or at a different distance {#faq-rotation-scale}

**Symptoms**

The template is found in the image it was cut from, but not in a new image in which the part is rotated or closer to or further from the camera.

**Possible causes**

- The defaults search the template at its original size and orientation only.

**Diagnostic procedure**

1. Read `input/rotation/min-rot`, `max-rot` and `input/scale/min-scale`, `max-scale` of the module. At the defaults (`0.0`, `0.0`, `1.0`, `1.0`) only the original orientation and size are searched.
2. Compare the part in the new image with the template. Expected: you know whether it varies in orientation, in size, or in both.

**Resolution**

Widen only what varies, one range at a time, and stop as soon as the part is found reliably:

- **If the part rotates:** set `input/rotation/max-rot` (for example `360`) with a coarse `input/rotation/step-rot` (for example `5`).
- **If the part changes distance:** set `input/scale/min-scale`, `input/scale/max-scale` and `input/scale/step-scale` (for example `0.9`, `1.1`, `0.05`).

Each scale/rotation combination is a separate pass over the image, so 72 rotations and 5 scales are 360 passes. If a wider range starts producing matches in the wrong places, see [Problem: A wide search reports weak matches in the wrong places](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#faq-spurious-matches). See [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/tuning-the-search.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the scale and rotation inputs and `output/result`.

### Problem: A wide search reports weak matches in the wrong places {#faq-spurious-matches}

**Symptoms**

With a scale or rotation range, `matches` holds the real match and, beside it, matches at unrelated places.

**Possible causes**

- The confidence is not an absolute measure. The score map is rescaled for every scale/rotation step, so the best location of every step reaches a confidence near 1, and `input/match-thresh` acts per step. Only repeats at the same location are removed, so a weak match somewhere else can still appear.

**Diagnostic procedure**

1. Read `matches[0]` and `best_score`. Expected: the real match is the highest-confidence entry, at index 0.
2. Read the scale and rotation inputs. A single-scale, single-rotation search behaves as expected; a range can report spurious matches.

**Resolution**

- Raise `input/match-thresh`, for example to `0.95`, or narrow the scale and rotation range.

See [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/tuning-the-search.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the inputs of `find-template` and `output/result`.

### Problem: `output/result` is empty although the search worked a moment ago {#faq-result-empty}

**Symptoms**

A run produced matches, and shortly afterwards `output/result` is empty.

**Possible causes**

- The next run has started. Every run clears its own outputs as soon as it begins, before anything that can fail. Triggering `execute` again and then reading gives the new run - possibly failed or still empty - not the previous one.
- A call refused with `-1` (busy) clears nothing, so this is not the cause when the second call was refused.

**Diagnostic procedure**

1. Check the order of the calls in your program. Expected: it reads `output/result` before it triggers the next `execute`.
2. Read `output/status-code` of the latest run. A negative value means that this run failed and left `output/result` empty.

**Resolution**

- **If the next run started too early:** wait for `execute` to return, read the outputs, and only then trigger the next run.
- **If the latest run failed:** follow the entry for its status code.

See [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/execute-a-method.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the sequence of calls your program makes.

## Templates {#ts-templates}

### Problem: The template file is on the device but missing from `system/templates` {#faq-template-not-listed}

**Symptoms**

A `.png` file is in the template folder, but `system/templates` does not list it.

**Possible causes**

- The file arrived by other means - an upload through the ctrlX web interface on ctrlX OS, or a file copied into the folder on a PC - and the list was not refreshed. The list is refreshed at startup, when `system/set-template-dir` succeeds and when `system/create-template` saves a template.
- The extension is not a lower case `.png`. `SCREW.PNG` is ignored.
- The file is in a different folder from the one in use.

**Diagnostic procedure**

1. Read `system/template-dir`. Expected: it names the folder that holds the file.
2. Check the file name. Expected: it ends in a lower case `.png`.

**Resolution**

- **If the extension is not a lower case `.png`:** rename the file to a lower case `.png`.
- **If the list was not refreshed:** execute `system/set-template-dir` again, naming the same folder. Expected: its status code is `1`, and `system/templates` lists the template.

A template added while the application runs can be searched for straight away: the file is read each time, not cached at startup. See [Template Storage](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/template-storage.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with `system/template-dir`, `system/templates` and the file name.

## Image stream (experimental) {#ts-stream}

### Problem: The image stream delivers no results {#ts-stream-no-results}

**Symptoms**

`control/subscribe/output/stream/active` stays `false`, no results arrive on `control/subscribe/output/stream/result`, or `control/subscribe/output/stream/statistics/failed-frames` grows.

**Possible causes**

- Only the inputs were written. Writing `control/subscribe/input/enable` alone starts nothing; `control/subscribe/execute` applies the inputs.
- `control/subscribe/execute` was refused (`Rejected`, ctrlX: `DL_INVALID_VALUE`): stream mode without an address, or a queue size outside `1` to `64`.
- The settings file `<module-id>.json` could not be written, for example because it is not valid JSON (`CreationFailed`, ctrlX: `DL_CREATION_FAILED`). Nothing changed.
- The stream of the Cam Driver does not run, so no frames arrive.
- The source cannot be subscribed to. The module tries it again every 5 seconds while the stream runs, and logs the first failure.
- Frames cannot be searched, for the reasons `find-template` gives in its `status-text`.

**Diagnostic procedure**

1. Read `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active`. Expected: `true`.
2. Read `setting/stream/enable` and `setting/stream/address` of the module. Expected: `true` and the camera’s stream folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`. They show what was applied last.
3. Check the answer of the write to `control/subscribe/execute`. Expected: `Ok` (ctrlX: `DL_OK`). These methods have no `status-text`; the reason for a refusal is in the application log.
4. Read `control/subscribe/output/stream/active`. Expected: `true`.
5. Read `received-frames`, `processed-frames` and `failed-frames` under `control/subscribe/output/stream/statistics/`. The first counter that does not grow shows where the chain stops.
6. If `failed-frames` grows, read `control/subscribe/output/stream/last-failure`. It says why the last frame failed, for example:
   ```
   a frame of 'hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream' failed: invalid input: template-name is empty
   ```

**Resolution**

- **If only the inputs were written:** set `control/subscribe/input/enable` to `true` and write to `control/subscribe/execute`. Wait until `control/subscribe/output/stream/active` is `true`.
- **If the call was refused (`Rejected`, `DL_INVALID_VALUE`):** write the camera’s stream folder to `control/subscribe/input/address`, set `control/subscribe/input/queue-size` to a value from `1` to `64`, and write to `control/subscribe/execute` again.
- **If the settings file could not be written (`CreationFailed`, `DL_CREATION_FAILED`):** make `<module-id>.json` in the configuration directory valid JSON again, without comments, then write to `control/subscribe/execute` again.
- **If the stream of the Cam Driver does not run:** start it. It is not kept after a restart: call its `control/publish/execute` with `enable` = `true` after every start, and connect the camera first. See [A stream delivers nothing](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#stream-nothing).
- **If the source cannot be subscribed to:** check that `control/subscribe/input/address` is the camera’s stream folder and that the Cam Driver runs on the same device.
- **If frames fail:** correct the input that `last-failure` names, as for a single `find-template` call.

See [Finding Templates on an Image Stream (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/processing-an-image-stream.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the values under `setting/stream/`, the counters under `control/subscribe/output/stream/statistics/`, `control/subscribe/output/stream/last-failure` and the module’s `<module-id>.json`.

## Modules, settings and licensing {#ts-modules}

### 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`, or a module’s inputs are back at their defaults.

**Possible causes**

- The module list was not saved. Settings and new modules are live at once but not permanent until saved; the module list and each module’s settings are saved separately.
- The module’s settings were not saved.
- A save failed: `system/save-module-inputs` or `system/save-current-modules` did not report status `1`.
- `<module-id>.json` contains comments. The stream reads such a file, but 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.

Results are not saved; they are produced by the next run. Template files are already permanent: they are files in the configuration directory, on ctrlX OS part of the active solution.

**Diagnostic procedure**

1. Read `system/modules` after the restart. Expected: all your modules.
2. Check the configuration directory (see [General checks](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#general-checks)). Expected: `lumiscan-template-finder.json` names your modules, and there is a `<module-id>.json` for each module whose settings you saved.
3. Read the application log of the start. Expected: no module file reported as unreadable, no skipped setting.

**Resolution**

- **If the settings or the module list were not saved:**

  a. Set `system/save-module-inputs/input/module-id` (for example `module-1`) and write to `system/save-module-inputs/execute`. Do this for each module.

  b. Write to `system/save-current-modules/execute`.

  c. Check that both report status `1`.

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

- **If a setting was skipped after an update:** set the input again and save the module’s settings.

A module’s image stream settings need no extra step: `control/subscribe/execute` saves them in `<module-id>.json` itself. To have the module itself back, save the module list as well. See [Module Management](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/module-management.html) and [Kept in the settings file](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/processing-an-image-stream.html#saving).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with `lumiscan-template-finder.json` and the module files `<module-id>.json`.

### Problem: The application stops shortly after starting {#faq-app-stops-after-start}

**Symptoms**

On ctrlX OS, the application shuts down shortly after it starts. Its nodes under `hdvisionsystems/lumiscan-template-finder` disappear from the Data Layer.

**Possible causes**

- The licence is missing. The reason is written to the system log.
- The application needs more licences than are installed. One licence covers ten modules, see [Problem: Status code `-11` (licence unavailable)](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#ts-licence-unavailable).

**Diagnostic procedure**

1. Open the ctrlX OS system log (ctrlX Logbook or `journalctl`). Expected: it names the reason and the missing licence.
2. Compare the licence with the ctrlX licence of LumiScan Template Finder, `SWL-W-XCx-TEMPLxFDxxHDVS-V1NN`. Expected: it is installed on the device on which the application runs.

**Resolution**

- **If the licence is missing:** install a valid licence on the device and start the application again. Expected: it keeps running, and its nodes are on the Data Layer.

See [Licence](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/requirements.html#licence) and [My ctrlX app stops shortly after starting](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/troubleshooting.html#faq-ctrlx-app-stops).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with the lines of the system log that name the licence. For licences, contact [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

### Problem: Status code `-11` (licence unavailable) {#ts-licence-unavailable}

**Symptoms**

A module is refused with status code `-11`.

**Possible causes**

- No licence on the device covers the module. One licence covers ten modules; the eleventh module acquires a second licence of the same key.

**Diagnostic procedure**

1. Count the entries of `system/modules`. Expected: no more than ten modules for each licence on the device.
2. Read `output/status-text` of the operation that answered `-11`.

**Resolution**

- **If more modules exist than the licences cover:** remove the modules you do not need with `system/remove-module` and save the module list with `system/save-current-modules`, or obtain another licence.

See [Module Management](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/lumiscan-template-finder/module-management.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#support-information) to support, together with `system/modules`. For licences, contact [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

## Information for support {#support-information}

If a problem persists, send this information to support:

- **Software version:** the version of LumiScan Template Finder you run. The files in `settings-history/` in the configuration directory record it as `software.version`.
- **Platform:** ctrlX OS (ctrlX CORE or ctrlX IPC) and its ctrlX OS version, or a PC with Windows 11 or Ubuntu 24.04. Also say where you bought the software: from HD Vision Systems or in the ctrlX Store.
- **Data Layer:** the ctrlX Data Layer (ctrlX OS) or LumiScan Keryx (PC). On a PC, also the Data Layer address the application uses.
- **Log:** the application log from the time of the error - on ctrlX OS from the ctrlX Logbook or `journalctl`, on a PC the application’s console output. Before you reproduce the problem, set `logLevel` to `TRACE` in the `system` block of `lumiscan-template-finder.json` and restart the application.
- **Time:** the date and time of the error.
- **Communication status:** `output/status-code` and `output/status-text` of the operation that failed, and the answer of the write to `execute` (for example `TooManyOperations` or `DL_TOO_MANY_OPERATIONS`).
- **Configuration files:** `lumiscan-template-finder.json`, the `<module-id>.json` of the module concerned, the template file and, for the image stream, the file in `settings-history/` that its settings hash names. Where they are is listed under [General checks](https://docs.hdvisionsystems.com/en/lumiscan-template-finder/1.1.0/troubleshooting.html#general-checks).

Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com). See also [Before you contact support](https://docs.hdvisionsystems.com/en/faq.html#faq-before-contacting-support) in the LumiScan FAQ.