---
title: "Troubleshooting"
description: "Problems and error messages of LumiScan Area Detector step by step - status codes, detection results, the image stream, modules, settings and licensing."
product: "LumiScan Area Detector"
component: "lumiscan-area-detector"
version: "1.2.0"
display_version: "1.2.0.6"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html"
---

# Troubleshooting – LumiScan Area Detector

This page describes problems and error messages of LumiScan Area Detector, grouped by category. Start with the [general checks](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.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; do not use the result then. The codes are listed in [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/execution-status.html).
2. **Read the status text.** Read `output/status-text` of the same operation. It starts with `ok:` or `error:` and names the offending value when there is one. 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 from the ctrlX Logbook or `journalctl`, on a PC from the application’s console output. How much is logged is set with `logLevel` in the `system` block of `lumiscan-area-detector.json` (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` or `OFF`). It is read at startup, so restart the application after you change it. See [Configuration file](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/datalayer-reference.html#configuration-file).
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-area-detector/1.2.0/troubleshooting.html#ts-app-stops-after-start).

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

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

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

### Problem: Status code `-1` (busy) {#faq-status-minus-1}

**Symptoms**

`output/status-code` of `detect-area` is `-1`. The write to `execute` answers `DL_TOO_MANY_OPERATIONS` (on a PC `TooManyOperations`). Nothing was done, and `output/result` and `output/blob-labels` keep their values. 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. The call is not queued; it returns at once and does nothing.
- The module’s image stream is searching a frame. The stream and `detect-area` 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. `system/analyse-scene` has its own lock and does not block detection.

- **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 read the latest result of the stream instead, set `control/subscribe/input/keep-latest-output` to `true` and read `detect-area/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-area-detector/1.2.0/lumiscan-area-detector/execute-a-method.html) and [detect-area while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/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-area-detector/1.2.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` of `detect-area` or `system/analyse-scene` is `-2`. `output/status-text` starts with `error:` and names the offending value. When several inputs are wrong, each one gets its own warning line in the log.

**Possible causes**

- A required input is empty.
- `input/method` is not `FIXED`. `FIXED` is the only method this version offers; anything else is refused.
- `input/preprocess/method` is unknown. It accepts `NONE`, `LOG`, `DOG` and `DOH`.
- A parameter is outside its range, for example `input/method-specific/fixed/level` outside 0-255, `input/preprocess/dog/sigma-first` equal to `sigma-second`, `input/preprocess/doh/kernel-size` other than 1, 3, 5 or 7, or `system/analyse-scene/input/histogram-bins` outside 2-256. Only the chosen preprocessing method’s parameters are validated.
- The image address points at this application itself.

**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.
3. Compare the inputs with the ranges in the [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/datalayer-reference.html).

**Resolution**

- **If a required input is empty:** set it.
- **If `input/method` is not `FIXED`:** set it to `FIXED`.
- **If `input/preprocess/method` is unknown:** set it to `NONE`, `LOG`, `DOG` or `DOH`.
- **If a parameter is outside its range:** correct it to a value inside the range given in the Data Layer Reference.
- **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`.

Then run the operation again. Expected: `output/status-code` is `1`. See [Execution Status](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/execution-status.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.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 `detect-area` or `system/analyse-scene` 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/analyse-scene` has its own address node, not a module’s.
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-area-detector/1.2.0/lumiscan-area-detector/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-area-detector/1.2.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: The crop region does not fit the image {#ts-crop-does-not-fit}

**Symptoms**

`detect-area` fails with a negative status code, and `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. A region reaching past an edge is refused rather than trimmed.

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

- 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, so all zero searches the whole image.

Then run `detect-area` again. Expected: `output/status-code` is `1`. See [Detecting Areas](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/detecting-areas.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.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` 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-area-detector/1.2.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-area-detector/1.2.0/troubleshooting.html#support-information) to support, together with the content of `output/status-text`.

## Detection results {#ts-results}

### Problem: Nothing is found, or the result is empty {#faq-nothing-found}

**Symptoms**

`output/status-code` of `detect-area` is `1`, but `blobs` in `output/result` is empty and `blob_count` is `0`.

**Possible causes**

An empty `blobs` list with status code `1` means that no regions matched, nothing else. Every other reason a run could produce nothing is reported as a negative status code. If the parts are there:

- `input/detect-dark` does not match which end the parts are. Set it to `true` when the parts are darker than the background.
- The level `input/method-specific/fixed/level` is above every pixel in the part.

**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-area-detector/1.2.0/troubleshooting.html#ts-status-codes).
2. Read `input/detect-dark`. Expected: `true` when the parts are darker than the background, `false` when they are brighter.
3. Run `system/analyse-scene` on the same image: set `system/analyse-scene/input/input-image-address` and write to `system/analyse-scene/execute`. Read `output/parts-are-dark` and `output/recommended-settings`. Expected: `input/detect-dark` and the level of the module match the advice.
4. Check the advice with `output/histogram`. Expected: the level sits in the valley between the part’s hump and the background’s.

**Resolution**

- **If `input/detect-dark` is wrong:** set it to `true` when the parts are darker than the background.
- **If the level is above every pixel in the part:** set `input/method-specific/fixed/level` to the level `output/recommended-settings` gives. Nothing is written for you.
- **If the histogram shows one hump:** no level will work; fix the lighting, see [Problem: The reading drifts with the lighting, or no level works](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-reading-drifts).

See [Analysing a Scene](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/analysing-a-scene.html) and [Detecting Areas](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/detecting-areas.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#support-information) to support, together with the inputs of `detect-area` and the outputs of `system/analyse-scene`.

### Problem: The measured area is larger or smaller than the part {#faq-area-wrong}

**Symptoms**

`blobs[0].area` or `total_area` differs from the real area of the part: much larger, consistently short, or a part with a hole measures as a ring.

**Possible causes**

- The area is much larger than the part: the level is letting background in.
- The area is consistently short: the level is trimming the part’s edge.
- `input/detect-dark` does not match which end the part is.
- The part has a hole, and `input/fill-holes` is off. A region is counted as the pixels that passed the threshold, so a hole is not counted unless `fill-holes` is set.

**Diagnostic procedure**

1. Measure a part whose real area you know, or count its pixels once in an image viewer, and compare it with `blobs[0].area`. Expected: they agree closely.
2. Look at the region in `output/blob-labels`: every pixel holding the region’s `blobs[].label` was counted. In the Cockpit, each region is tinted in its own colour over the camera picture.
3. Read `input/detect-dark` and `input/fill-holes`.

**Resolution**

- **If the level is letting background in:** check `input/detect-dark`, then commission the level again with `system/analyse-scene`, see [Problem: Nothing is found, or the result is empty](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#faq-nothing-found).
- **If the area is consistently short:** lower `input/method-specific/fixed/level`, and try `input/detect-dark` if the part is the darker of the two.
- **If a part with a hole measures as a ring:** turn on `input/fill-holes` to measure the shape its outline encloses. A washer then measures as a disc.

See [Tuning the Detection](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/tuning-the-detection.html) and [How To: Measure Part Area from a Camera Image](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/how-tos/measure-part-area-from-a-camera-image.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#support-information) to support, together with the inputs of `detect-area`, `output/result` and the area you expected.

### Problem: Many tiny regions are reported {#faq-tiny-regions}

**Symptoms**

`blob_count` is much higher than the number of parts, and `blobs` holds many entries with a small `area`.

**Possible causes**

- Sensor noise and dust cross the threshold. The application reports every region it separated; there is no area window.

**Diagnostic procedure**

1. Look at the smallest entries in `blobs`. Expected: their `area` is far below the area of a part.
2. Look at those regions in `output/blob-labels`.

**Resolution**

Deal with noise and dust in one of two places:

- **At the level:** raise `input/method-specific/fixed/level` until the noise stops crossing the threshold. This is the better fix, because those regions then cost nothing to find.
- **In your control program:** ignore `blobs[]` entries whose `area` is below what a part can be. A quarter of the area of the smallest part you care about is a good starting point.

See [Tuning the Detection](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/tuning-the-detection.html).

**If the problem persists**

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

### Problem: One part is reported as several regions {#faq-part-split}

**Symptoms**

One part appears as several entries in `blobs`; in `output/blob-labels` its pixels carry several labels.

**Possible causes**

- The part is being split by a shadow or a highlight.

**Diagnostic procedure**

1. Look at the part in `output/blob-labels`. In the Cockpit, neighbouring regions come back as different colours.
2. Compare the split with the camera picture. Expected: a shadow or a highlight runs where the part is split.

**Resolution**

- Try preprocessing with `input/preprocess/method` (`LOG`, `DOG` or `DOH`), or `input/detect-dark`. All three filters normalise their output, so revisit the level after enabling one.

See [Detecting Areas](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/detecting-areas.html) and [Tuning the Detection](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/tuning-the-detection.html).

**If the problem persists**

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

### Problem: The reading drifts with the lighting, or no level works {#faq-reading-drifts}

**Symptoms**

The measured area changes when the lighting changes, does not settle, or no level separates the parts from the background.

**Possible causes**

- The picture is brittle: `system/analyse-scene/output/area-sensitivity` is above `0.05`, so one grey level costs 5 % of the measured area, and a fixed level is not safe to commission. No value in `detect-area/input/` repairs this; it is fixed at the camera.
- Uneven lighting: the light varies more than about a third of the part-to-background gap.
- The features are too fine: below about 8 px.
- The edges are soft (defocus, motion blur, sensor noise at high gain), or the contrast is low.

**Diagnostic procedure**

1. Run `system/analyse-scene` on the image and read `output/area-sensitivity`. Expected: well below `0.05` - `0.01` is still comfortable; above `0.05` the picture is brittle.
2. Read `output/findings`. It says in words which lever it hit, most important first.
3. Read `output/illumination-spread` against the part-to-background gap. Expected: less than about a third of the gap.
4. Read `output/feature-thickness`. Expected: about 8 px or more.

**Resolution**

Work through the levers in this order:

- **If the lighting is uneven:** fix the uneven lighting first. No single level fits the frame.
- **If the features are below about 8 px:** put more pixels on the part: magnification, a closer working distance, or a higher resolution sensor.
- **If the edges are soft:** refocus, shorten the exposure or steady the part, drop the gain and add light instead.
- **If the contrast is low:** change the lighting: backlight, another angle, a diffuser or a polariser, another background.

A high `area-sensitivity` under a steady lamp is a constant offset; it costs you only when the lighting or the threshold moves. See [Analysing a Scene](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/analysing-a-scene.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#support-information) to support, together with all outputs of `system/analyse-scene`.

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

**Symptoms**

A run produced regions, and shortly afterwards `output/result` (and `output/blob-labels`) 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-area-detector/1.2.0/lumiscan-area-detector/execute-a-method.html).

**If the problem persists**

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

## 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 (`DL_INVALID_VALUE`, on a PC `Rejected`): 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 (`DL_CREATION_FAILED`, on a PC `CreationFailed`). 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 `detect-area` 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: `DL_OK` (on a PC `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: preprocess/method 'LAPLACE' is unknown; expected NONE, LOG, DOG or DOH
   ```

**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 (`DL_INVALID_VALUE`, `Rejected`):** 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 (`DL_CREATION_FAILED`, `CreationFailed`):** 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 `detect-area` call.

The stream publishes the measurements only: `output/blob-labels` has no stream counterpart. See [Detecting Areas on an Image Stream (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/processing-an-image-stream.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.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.

**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-area-detector/1.2.0/troubleshooting.html#general-checks)). Expected: `lumiscan-area-detector.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.

The image stream’s mode and source are saved by `control/subscribe/execute` itself, in the module’s `<module-id>.json`; they come back only if the module list is saved too. See [Module Management](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/module-management.html) and [Kept in the settings file](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/lumiscan-area-detector/processing-an-image-stream.html#saving).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.0/troubleshooting.html#support-information) to support, together with `lumiscan-area-detector.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-area-detector` 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-area-detector/1.2.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 Area Detector, `SWL-W-XCx-AxxDETECTxHDVSx-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-area-detector/1.2.0/lumiscan-area-detector/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-area-detector/1.2.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-area-detector/1.2.0/lumiscan-area-detector/module-management.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-area-detector/1.2.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 Area Detector 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 `DL_TOO_MANY_OPERATIONS` or `TooManyOperations`).
- **Configuration files:** `lumiscan-area-detector.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-area-detector/1.2.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.