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

# Troubleshooting – LumiScan Object Finder

This page describes problems and error messages of LumiScan Object Finder, grouped by category. Start with the [general checks](https://docs.hdvisionsystems.com/en/lumiscan-object-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-object-finder/1.1.0/lumiscan-object-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-object-finder.json` (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` or `OFF`). It is read at startup, so restart the application after you change it. See [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/datalayer-reference.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-object-finder/1.1.0/troubleshooting.html#ts-app-stops-after-start).

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

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

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

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

**Symptoms**

`output/status-code` of `find-object` 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-object` 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-object/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-object-finder/1.1.0/lumiscan-object-finder/execute-a-method.html) and [find-object while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-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-object-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) {#ts-status-minus-2}

**Symptoms**

`output/status-code` is `-2`. `output/status-text` starts with `error:` and names each input that cannot be used, together with the value it holds. All invalid inputs are reported together.

**Possible causes**

- A required input is empty. `input/object-id` of `find-object` is required.
- The image address points at this application itself.
- `input/object-id` of `system/create-object` or `input/object-dir` of `system/set-object-dir` is an absolute path, or a path that climbs out of the configuration directory with `..`.

**Diagnostic procedure**

1. Read `output/status-text` of the operation. Expected: it names the offending input and its value.
2. Read the application log. Each invalid input has its own warning line.

**Resolution**

- **If a required input is empty:** set it. For `find-object`, set `input/object-id` to an entry of `system/objects`.
- **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, for example `production-parts`.

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

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-object-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-object` or `system/create-object` 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.
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-object-finder/1.1.0/lumiscan-object-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-object-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-object` is `-4`.

**Possible causes**

- The object’s picture is missing or unreadable: `input/object-id` names no entry of `system/objects`.
- The object directory is missing or unreadable.
- The picture is in another directory than the one in use.

**Diagnostic procedure**

1. Compare `input/object-id` with `system/objects`. Expected: the id is listed, spelled the same way.
2. Read `system/object-dir`. Expected: it names the directory that holds the object’s `.png`.
3. Check the file in that directory. Expected: a lower case `.png` at the top of the directory, named after the object.

**Resolution**

- **If the object id is not listed:** correct `input/object-id`, or teach the object with `system/create-object`. A file you put into the directory by other means is listed only after a refresh, see [Problem: An uploaded `.png` does not appear on `system/objects`](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#faq-object-not-listed).
- **If the directory is not the one you expect:** switch with `system/set-object-dir`, see [Object Storage](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/object-storage.html).

Then run `find-object` 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-object-finder/1.1.0/troubleshooting.html#support-information) to support, together with the content of `output/status-text`, `input/object-id`, `system/object-dir` and `system/objects`.

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

**Symptoms**

`system/create-object` answers status `-5` (invalid crop region), and `output/status-text` names the edge and the image size, for example:

```
error: Crop region does not fit inside the 1920x1080 image: crop/startY + crop/height (1000 + 200 = 1200) exceeds the image height 1080
```

For `find-object`, `output/status-text` names the input and the limit it broke, for example `error: crop/startX + crop/width (100 + 900 = 1000) 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. The whole crop must lie inside the image; it is refused, not trimmed.
- For `system/create-object`, `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.

**Resolution**

- **If the region reaches past an edge:** correct `input/crop/startX`, `startY`, `width` or `height`, so that the region fits the image size given in the message.
- **If width or height is 0 (`create-object`):** set both to the size of the region, greater than 0.

Then run the operation again. Expected: `output/status-code` is `1`. See [Creating an Object](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/creating-an-object.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-object-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: The run fails and names the object {#faq-object-refused-bin-size}

**Symptoms**

`find-object` fails with a negative status code, and `output/status-text` names the object. This often happens after `input/preprocess/bin-size` was raised. It is never reported as an empty result.

**Possible causes**

- The object is binned too far. Its picture then no longer has the edges the detector keys on, and the detector refuses it, for example a 128x128 object at `bin-size` 8 (reduced to 16x16). Small objects reach this limit sooner than large ones.
- The picture was cropped along the part’s silhouette when the object was taught. A picture must yield a minimum number of strong gradient points, and a crop that stops at the silhouette hides the outline from the detector.

**Diagnostic procedure**

1. Read `input/preprocess/bin-size` of the module. Lower it by one step and run `find-object` again. Expected: `output/status-code` is `1`.
2. If the run still fails at `bin-size` `1`, open the object’s `.png` in the object directory. Expected: a thin, even band of background, about 5 pixels, around the part.

**Resolution**

- **If the object is binned too far:** lower `input/preprocess/bin-size` again. Raise it one step at a time and stop when the scores start dropping towards the threshold.
- **If the picture was cropped at the silhouette:** teach the object again with `system/create-object`, with about 5 pixels of background around the part. See [Creating an Object](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/creating-an-object.html).

See [Tuning the Search: Bin size](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/tuning-the-search.html#bin-size).

**If the problem persists**

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

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

**Symptoms**

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

**Possible causes**

- A file could not be written - usually a permission problem or a full disk.

**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 at the time of the call.
3. Check the configuration directory (see [General checks](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#general-checks)). Expected: it exists and the application can write to it.

**Resolution**

- **If it is a permission problem:** make the configuration directory 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-object-finder/1.1.0/troubleshooting.html#support-information) to support, together with the content of `output/status-text`.

## Search results {#ts-results}

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

**Symptoms**

`output/status-code` of `find-object` is `1`, but `matches` in `output/result` is empty (`best_score` `0.0`, `best_object_id` empty). Or a genuine part is found in some images and missed in others: only in some orientations, or only at some working distances.

**Possible causes**

An empty result with status code `1` means that the object was not in the searched image, and nothing else. Every other reason - missing picture, unusable image, invalid pyramid level, `bin-size` leaving too little of the object - is reported as a negative status code. If a genuine part is missed:

- `input/crop` excludes the part.
- The scores of the genuine parts are below `input/confidence-threshold` (default `0.6`). A threshold at or above `0.9` usually rejects everything.
- The part arrives in an orientation that no object was taught for. The detector does not rotate a picture.
- The part sits closer to or further from the camera than in the picture it was taught from.

**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-object-finder/1.1.0/troubleshooting.html#ts-status-codes).
2. Check that `input/object-id` is listed on `system/objects`.
3. Read the four `input/crop/` values. Expected: all `0` (the whole image), or a region that contains the part.
4. Set `input/confidence-threshold` to `0.4`, run against real parts and note the `score` of the genuine matches in `output/result`. Expected: the threshold you use lies below the worst score of a genuine part.
5. Compare an image in which the part is missed with the image the object was taught from. Expected: the same orientation and working distance.

**Resolution**

- **If the crop excludes the part:** widen the region, or set all four `input/crop/` values to `0`.
- **If the scores are just below the threshold:** set `input/confidence-threshold` a little below the worst score a genuine part produces. If the scores hover near the threshold or the images are noisy, set `input/preprocess/blur-sigma-x` to `1.0` (blur is off by default) and measure again.
- **If the part is missed at particular orientations:** teach another object at the orientation being missed, for example `screw-m6-tilted`, and search for it in its own run. No setting fixes this.
- **If the part is missed at another working distance:** teach an object at that distance.
- **If the part was not in the image:** the result is correct; nothing needs to be changed.

See [Finding an Object](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/finding-an-object.html) and [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/tuning-the-search.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#support-information) to support, together with `input/object-id`, the threshold, the scores you measured and the object’s `.png`.

### Problem: One part is reported several times {#faq-duplicate-matches}

**Symptoms**

`matches` in `output/result` holds a cluster of matches a few pixels apart for one part.

**Possible causes**

- `input/nms-min-dist` is `0` (the default), which keeps every match.
- `input/nms-min-dist` is smaller than the distance between the matches of one part.

**Diagnostic procedure**

1. Read `input/nms-min-dist` of the module. `0` keeps every match.
2. Compare `x` and `y` of the matches of one part with the size of the part in pixels.

**Resolution**

- Set `input/nms-min-dist` to roughly half the size of the part in pixels, for example `40`. Where several matches fall within that distance, only the highest scoring one is kept.

The default of `0` is only useful when parts genuinely sit closer together than their own size. See [Tuning the Search](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/tuning-the-search.html).

**If the problem persists**

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

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

**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. A run that fails for any reason leaves them empty.
- 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-object-finder/1.1.0/lumiscan-object-finder/execute-a-method.html).

**If the problem persists**

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

## Objects {#ts-objects}

### Problem: An uploaded `.png` does not appear on `system/objects` {#faq-object-not-listed}

**Symptoms**

A `.png` file is in the object directory, but `system/objects` does not list it.

**Possible causes**

- The list was not refreshed. `system/objects` is refreshed only at startup, when `system/set-object-dir` switches directory and when `system/create-object` saves a template. Files added by other means - an upload or an SSH session on ctrlX OS, a file copied in by hand on a PC - are picked up at the next of these.
- The file name does not end in a lower case `.png`. `.PNG` files are skipped.
- The file is in a subdirectory. Only files at the top of the object directory are listed.
- The file is in another directory than the one `system/object-dir` names.

**Diagnostic procedure**

1. Read `system/object-dir`. Expected: it names the directory that holds the file.
2. Check the file name. Expected: it ends in a lower case `.png`, and the file is at the top of the directory.

**Resolution**

- **If the file name or the place is wrong:** use a lower case `.png` file name at the top of the object directory.
- **Then:** run `system/set-object-dir` or restart the application. Expected: `system/objects` lists the object.

See [Object Storage](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-finder/object-storage.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/troubleshooting.html#support-information) to support, together with `system/object-dir`, `system/objects` 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-object` 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: object-id is empty - name the object to search for, see system/objects
   ```

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

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

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-object-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 take effect immediately but are not saved until you ask; 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.

**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-object-finder/1.1.0/troubleshooting.html#general-checks)). Expected: `lumiscan-object-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-object-finder/1.1.0/lumiscan-object-finder/module-management.html) and [Kept in the settings file](https://docs.hdvisionsystems.com/en/lumiscan-object-finder/1.1.0/lumiscan-object-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-object-finder/1.1.0/troubleshooting.html#support-information) to support, together with `lumiscan-object-finder.json` and the module files `<module-id>.json`.

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

**Symptoms**

On ctrlX OS, the application shuts down shortly after it starts. Its nodes under `hdvisionsystems/lumiscan-object-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-object-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 Object Finder, `SWL-W-XCx-OBJECTxFDxHDVS-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-object-finder/1.1.0/lumiscan-object-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-object-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-object-finder/1.1.0/lumiscan-object-finder/module-management.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-object-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 Object 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.
- **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-object-finder.json`, the `<module-id>.json` of the module concerned 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-object-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.