---
title: "Troubleshooting"
description: "Problems with LumiScan QR Code Reader step by step - a reader that shuts down during start-up, an empty result, refused stream calls, a stream without results and a stream that starts again by itself."
product: "LumiScan QR Code Reader"
component: "lumiscan-qr-code-reader"
version: "1.0.0"
display_version: "1.0.0.5"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html"
---

# Troubleshooting – LumiScan QR Code Reader

This page describes problems with LumiScan QR Code Reader and how you solve them. Start with the [general checks](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.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. **Read the application log.** The application log is the ctrlX OS system log (ctrlX OS) or the console output of the app (PC). The reader writes the reason there when a run fails, when `control/subscribe/execute` or `control/unsubscribe/execute` is refused, when the source of the image stream cannot be subscribed to (the first failure), when frames cannot be read (at most one line every 5 seconds), and when a value in its settings file cannot be used.

2. **Check the addresses.** All nodes are directly under `hdvisionsystems/lumiscan-qr-code-reader/`; the reader has no modules. Addresses are lower case. Expected: your PLC or client uses exactly these addresses, as listed in the [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/datalayer-reference.html).

3. **Check the image source.** The application that publishes the image node, normally LumiScan Cam Driver, must run on the **same ctrlX CORE or ctrlX IPC** (ctrlX OS) or be connected to the same LumiScan Keryx broker as the reader (PC, see [LumiScan Keryx on a PC](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html)). Expected: the node named in `input/image-address` provides `data`, `width`, `height` and `pixel-type`.

4. **Check whether a run failed.** This reader publishes no `status-code` or `status-text` node. A failed run leaves `output/results` untouched, holding the previous run’s codes. Read `output/results` before and after the run and compare, or check the log. See [How do I know whether a run failed?](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/faq.html#faq-failed-run).

5. **Check the settings file of the image stream.** The reader keeps its stream settings in `qr-code-reader.json` in the application’s configuration directory:

   | Platform | Configuration directory |
   | --- | --- |
   | ctrlX OS | `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-qr-code-reader` |
   | PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-qr-code-reader`; without `APP_RESOURCE_DIR`, `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-qr-code\etc\lumiscan-qr-code-reader` |

   The file is read once, at the start of the application: changes made to it by hand take effect at the next start. A value that cannot be used is ignored, and logged; a file that is not valid JSON is ignored, and logged. See [Kept in the settings file](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-codes-on-an-image-stream.html#saving).

## Problem: The reader shuts down during start-up {#faq-app-stops-after-start}

**Symptoms**

On ctrlX OS, the reader stops shortly after it starts. Its nodes under `hdvisionsystems/lumiscan-qr-code-reader` disappear from the Data Layer.

**Possible causes**

- The ctrlX licence `SWL-W-XCx-QRxxxCRDSxHDVSx-V1NN` is not available on the ctrlX OS device on which the reader runs. The licence is checked for up to ten seconds during start-up; if none becomes available, the reader shuts down.

**Diagnostic procedure**

1. Open the ctrlX OS system log - expected: the reason for the shutdown. The system log names the missing licence.
2. Check the licences in the License Manager of ctrlX OS - expected: the ctrlX licence `SWL-W-XCx-QRxxxCRDSxHDVSx-V1NN` is available on the device on which the reader runs. One licence seat covers the reader. The Advanced licence `SWL-W-XCx-QRxxxCRDAxHDVSx-V1NN` is not needed to start: without it, the reader runs with Standard functions.

**Resolution**

- **If the ctrlX licence is missing:**

  a. Buy the licence `SWL-W-XCx-QRxxxCRDSxHDVSx-V1NN` in the ctrlX Store.

  b. Activate it in the License Manager of ctrlX OS on the device on which the reader runs. Follow the Bosch Rexroth documentation for ctrlX OS.

  c. Start the reader again. Expected: it keeps running, and its nodes are on the Data Layer.

See [Licence](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/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-qr-code-reader/1.0.0/troubleshooting.html#support-information) to support, together with the lines of the ctrlX OS system log that name the licence. For licences, contact [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

## Problem: `output/results` is an empty array {#faq-empty-result}

**Symptoms**

After `execute` returns, `output/results` holds an empty array: `CodeDetectResultArray.results` has no entry. In the image stream, a result on `control/subscribe/output/stream/result` has an empty `results` array.

**Possible causes**

- The image holds no QR code. An empty `output/results` is not an error: it means the image was read successfully and contained no QR code. A run that found nothing publishes an empty array rather than an error.
- The code is not a QR code. The reader reads QR codes, the 2D symbology with a square finder pattern in three corners. Data Matrix codes, Aztec codes and linear barcodes are read by its sibling applications.
- `input/image-address` names an image node that does not show the code. Each run reads the entire current contents of the image node named there.
- The last run failed, and the empty array is the result of an earlier run. A failed run leaves `output/results` untouched. A run fails if the image cannot be read: no address set, an address that does not resolve, a missing or short `data` buffer, or an unsupported pixel format.

**Diagnostic procedure**

1. Read the application log for the time of the run - expected: no failure. A failed run writes its reason there: the ctrlX OS system log (ctrlX OS) or the console output of the app (PC).
2. Read `input/image-address` - expected: the address of the image node of the camera that sees the code, for example `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
3. Check the type of the code - expected: a QR code, with a square finder pattern in three corners.

**Resolution**

- **If the image holds no QR code:** nothing is wrong with the reader. Call `execute` again when the image node holds a picture with the code.

- **If the code is not a QR code:** use the sibling application for its symbology: LumiScan DMC Reader, LumiScan Aztec Code Reader or LumiScan Barcode Reader. They work the same way.

- **If `input/image-address` names another image node:**

  a. Write the address of the right image node to `input/image-address`. It is the address of the image node itself, not of its `data` child. The address is remembered.

  b. Write an empty value to `execute`. Expected: `output/results` holds an entry per code.

- **If the last run failed:** remove the reason the log names: set `input/image-address`, correct an address that does not resolve, or make the image source deliver complete `data` in a supported pixel format (see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/requirements.html)). Then write an empty value to `execute` again. Expected: the log shows no failure for this run.

See [Reading a Code](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-a-code.html) and [The Result](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/the-result.html).

**If the problem persists**

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

## Problem: `control/subscribe/execute` answers `Rejected` (ctrlX `DL_INVALID_VALUE`) or `CreationFailed` (ctrlX `DL_CREATION_FAILED`) {#faq-stream-refused}

**Symptoms**

A write to `control/subscribe/execute` (or to `control/unsubscribe/execute`) answers `Rejected` (ctrlX `DL_INVALID_VALUE`) or `CreationFailed` (ctrlX `DL_CREATION_FAILED`) instead of `Ok` (ctrlX `DL_OK`). Nothing changed: `setting/stream/` still shows the values applied before.

**Possible causes**

- `Rejected` / `DL_INVALID_VALUE` from `control/subscribe/execute`: stream mode without an address, or a queue size outside `1` to `64`.
- `Rejected` / `DL_INVALID_VALUE` from `control/unsubscribe/execute`: the address is not the source, or there is no source.
- `CreationFailed` / `DL_CREATION_FAILED`: the settings file `qr-code-reader.json` could not be written, for example because it is not valid JSON.

**Diagnostic procedure**

1. Read the answer of the method call - expected: `Ok` or `DL_OK`. `Rejected` or `DL_INVALID_VALUE` points to an input, `CreationFailed` or `DL_CREATION_FAILED` to the settings file.
2. Read the application log - expected: the reason for the refusal. On the ctrlX Data Layer a refused call carries no reason; the reader writes it to its log.
3. After a refused `control/subscribe/execute`, read `control/subscribe/input/enable`, `control/subscribe/input/address` and `control/subscribe/input/queue-size` - expected: an address whenever `enable` is `true`, and a queue size from `1` to `64`.
4. After a refused `control/unsubscribe/execute`, compare `control/unsubscribe/input/address` with `setting/stream/address` - expected: the same address. A `/` at either end does not count.
5. After `CreationFailed` or `DL_CREATION_FAILED`, open `qr-code-reader.json` in the configuration directory (see [General checks](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#general-checks)) - expected: a valid JSON file.

**Resolution**

- **If stream mode has no address:** write the camera’s stream folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, to `control/subscribe/input/address`, then write to `control/subscribe/execute` again. Expected: `Ok` or `DL_OK`.

- **If the queue size is outside `1` to `64`:** write a value from `1` to `64` to `control/subscribe/input/queue-size`, then write to `control/subscribe/execute` again. Expected: `Ok` or `DL_OK`.

- **If the address to drop is not the source:** write the address that `setting/stream/address` shows to `control/unsubscribe/input/address`, then write to `control/unsubscribe/execute` again. If `setting/stream/address` is empty, there is no source to drop.

- **If the settings file could not be written:**

  a. Correct `qr-code-reader.json` so that it is valid JSON. On a PC, `lumiscan-qr-code --generate-settings <folder>` writes an example to start from.

  b. Write to `control/subscribe/execute` again. Expected: `Ok` or `DL_OK`, and `setting/stream/` shows the new values.

     Changes made to the file by hand take effect at the next start of the application.

See [Changing the source](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-codes-on-an-image-stream.html#subscribing) and [Results of a method call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#method-results).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#support-information) to support, together with the answer of the method call, the values of the inputs of `control/subscribe` (or `control/unsubscribe/input/address`) and `qr-code-reader.json`.

## Problem: The stream runs, but no results arrive, or `failed-frames` grows {#faq-stream-no-results}

**Symptoms**

After `control/subscribe/execute`, no result arrives on `control/subscribe/output/stream/result`, or the counter `control/subscribe/output/stream/statistics/failed-frames` grows.

**Possible causes**

- The reader’s stream does not run: the inputs of `control/subscribe` were written, but `control/subscribe/execute` was not called. Writing an input alone changes nothing.
- No frames arrive from the source: the Cam Driver’s stream does not run, or `control/subscribe/input/address` is not the camera’s stream folder. The Cam Driver’s stream is not kept across a restart of the Cam Driver.
- The source cannot be subscribed to. The reader then tries it again every 5 seconds while the stream runs.
- Frames arrive but cannot be read, for example frames in a pixel format the reader does not support, or frames whose pixels do not fill the size they give.
- Results are published, but your client does not subscribe to `control/subscribe/output/stream/result`. A read of the node returns only the latest result.

**Diagnostic procedure**

1. Read `control/subscribe/output/stream/active` - expected: `true`. If it is `false`, read `setting/stream/enable` and `setting/stream/address` - expected: `true` and the camera’s stream folder.
2. Read `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active` - expected: `true`.
3. Read `control/subscribe/output/stream/statistics/received-frames` twice, a few seconds apart - expected: the value grows. The counters are updated about four times a second while the stream runs.
4. Read `statistics/failed-frames` and `control/subscribe/output/stream/last-failure` - expected: `failed-frames` does not grow, and `last-failure` is empty. `last-failure` says why the last frame that could not be read failed; it is emptied when the stream starts.
5. Read `statistics/processed-frames` - expected: the value grows. Each processed frame has a result published on `control/subscribe/output/stream/result`.
6. Read the application log - expected: no failure to subscribe to the source, and no failed frames.

**Resolution**

- **If the reader’s stream does not run:**

  a. Write the camera’s stream folder to `control/subscribe/input/address`.

  b. Set `control/subscribe/input/enable` to `true`.

  c. Write to `control/subscribe/execute`. Expected: `Ok` or `DL_OK`, then `control/subscribe/output/stream/active` is `true`.

- **If the Cam Driver’s stream does not run:** start it, see the Cam Driver manual, *Streaming Images*. Its stream is not kept across a restart: after every start of the Cam Driver, connect the camera and call its `control/publish/execute` with `enable` = `true`. The reader’s stream can be started before the Cam Driver’s stream; results arrive once frames do.

- **If the address is not the camera’s stream folder:** write the folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, to `control/subscribe/input/address` and write to `control/subscribe/execute`. The reader reads the folder’s `frame` node. Expected: `received-frames` grows.

- **If the source cannot be subscribed to:** make sure the Cam Driver runs and publishes the stream folder named in `control/subscribe/input/address`. While the stream runs, the reader tries the source again every 5 seconds; for the same address you do not need to execute again.

- **If frames cannot be read:** read `control/subscribe/output/stream/last-failure` for the reason. Make sure the frames use a supported pixel format: `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `Bayer_GR8`, `Bayer_RG8`, `Bayer_GR12` or `Bayer_RG12` (see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/requirements.html)). Expected: `failed-frames` stops growing.

- **If `processed-frames` grows but your client receives nothing:** subscribe to `control/subscribe/output/stream/result` to receive each result. Or set `control/subscribe/input/keep-latest-output` to `true` and write to `control/subscribe/execute`: the reader then also writes each stream result to `output/results`. `krxclient subscribe hdvisionsystems/lumiscan-qr-code-reader/control/subscribe/output/stream/result --count 5` shows that results arrive; it shows a flatbuffer by its size only.

A frame with no QR code gives a result with an empty `results` array, see [Problem: `output/results` is an empty array](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#faq-empty-result). See also [Reading the statistics](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-codes-on-an-image-stream.html#statistics) and [A stream delivers nothing](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#stream-nothing).

**If the problem persists**

The image stream is experimental. On ctrlX OS, it has not been verified on Linux, on the ctrlX Data Layer, or with a real camera. On a PC, it has been tested on Windows with LumiScan Keryx and simulated images only; it has not been verified with a real camera. Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#support-information) to support, together with the values of `control/subscribe/output/stream/active`, `control/subscribe/output/stream/last-failure`, the counters under `control/subscribe/output/stream/statistics/` and `setting/stream/`, and the value of the Cam Driver’s `control/publish/output/stream/active`.

## Problem: After a restart the reader streams again by itself {#faq-stream-restart}

**Symptoms**

After a restart of the application, `control/subscribe/output/stream/active` is `true` and results arrive on `control/subscribe/output/stream/result`, although your program has not executed anything.

**Possible causes**

- The reader starts as it was. This is intended: `control/subscribe/execute` and `control/unsubscribe/execute` save what they apply in the `stream` member of `qr-code-reader.json`. After a restart the reader subscribes to the same source and, when `stream.enable` is `true`, starts its stream at once.
- `stream.enable` was set to `true` in `qr-code-reader.json` by hand. `true` starts the stream at the start of the application.

**Diagnostic procedure**

1. Read `setting/stream/enable` and `setting/stream/address` - they show what was applied last, as the settings file keeps it. Expected, if the reader should not stream after a start: `setting/stream/enable` is `false`.
2. Open `qr-code-reader.json` in the configuration directory (see [General checks](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#general-checks)) - expected, if the reader should not stream after a start: `stream.enable` is `false` or left out.

**Resolution**

- **If the reader should not stream after a start:** set `control/subscribe/input/enable` to `false`, then write to `control/subscribe/execute`. This stops the stream now and is saved in `qr-code-reader.json`, so the reader starts out of stream mode next time. The frame being read is finished first. Expected: `control/subscribe/output/stream/active` is `false`, and `setting/stream/enable` is `false`.
- **If the reader should not keep the source either:** write the address that `setting/stream/address` shows to `control/unsubscribe/input/address`, then write to `control/unsubscribe/execute`. Stream mode ends with it. Expected: `setting/stream/address` is empty.

See [Kept in the settings file](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-codes-on-an-image-stream.html#saving).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#support-information) to support, together with `qr-code-reader.json` and the values of `setting/stream/`.

## Information for support {#support-information}

If a problem persists, send this information to support:

- **Software version:** the version of LumiScan QR Code Reader you run. The files the image stream keeps 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.
- **Data Layer:** the ctrlX Data Layer (ctrlX OS) or LumiScan Keryx (PC). On a PC, also the broker address the reader uses; each app names it in its log at start.
- **Log:** the application log from the time of the error: the ctrlX OS system log (ctrlX OS) or the console output of the app (PC).
- **Time:** the date and time of the error.
- **Communication status:** the answer of a refused method call (for example `Rejected` or `DL_INVALID_VALUE`), and the node values that the problem entry asks for.
- **Configuration files:** `qr-code-reader.json` and the files in `settings-history/` from the configuration directory (see [General checks](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.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).