---
title: "Troubleshooting"
description: "Step-by-step help for LumiScan Calibration problems - modules that do not appear, old addresses, transform/ready stays false, requests without reaction, wrong coordinates and streams."
product: "LumiScan Calibration"
component: "lumiscan-calibration"
version: "2.0.0"
display_version: "2.0.0.8"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html"
---

# Troubleshooting – LumiScan Calibration

This page first lists the general checks that help with every problem. Start with them. Then find your symptom in the categories below: each problem lists its symptoms, possible causes, a diagnostic procedure and the resolution. The last section lists what to send to support.

## General checks {#general-checks}

### Configuration {#general-configuration}

LumiScan Calibration uses:

- an application configuration file (`lumiscan-calibration.json`) that references
- one or more module configuration files (`<module name>.json`), each naming a TIFF file.

The configuration files can be found under:

- **On ctrlX OS:** **Manage App Data > active > lumiscan-calibration**
- **On a PC (Windows):** `%APP_RESOURCE_DIR%\etc\lumiscan-calibration`, or without `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration`

Their content is also shown on the Data Layer, on `hdvisionsystems/lumiscan-calibration/system/settings`. A module file that could not be read appears there with an `"$error"` that says why. See [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html).

Restart LumiScan Calibration after changing `lumiscan-calibration.json`. After changing a module configuration file or its TIFF file, a reset of the module (`control/reset`) is enough.

For more information about the configuration files, see [Application Settings File](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/application-settings-file.html) and [Module Configuration File](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/module-configuration-file.html).

### Status of the application and its modules {#general-status}

- `hdvisionsystems/lumiscan-calibration/system/found-modules` lists the modules the application serves. `hdvisionsystems/lumiscan-calibration/system/status-text` is `"Initialized"` once it serves its modules, or says why it serves none.
- `hdvisionsystems/lumiscan-calibration/<module name>/control/status/code` and `.../control/status/text` report the outcome of the last function. An error status stays until the next request. The meaning of each value is listed in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/functionalities.html#status-code-values).
- Status `-5` (`restartRequired`) means that the settings were changed on the Data Layer: restart the application with `hdvisionsystems/lumiscan-calibration/system/control/restart/execute`. See [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/settings-on-the-data-layer.html#restart-required).

### Logs {#general-logs}

If an issue cannot be resolved using the checks described below, review the log. Each module writes why it could not load its files or start its stream.

- **ctrlX OS:** the ctrlX OS system log. Read it in the Logbook of the ctrlX web interface, or with `journalctl`. See [ctrlX Data Layer on ctrlX OS](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html).
- **PC:** the output of LumiScan Calibration in its console.

### Data Layer {#general-data-layer}

For problems with the Data Layer itself, see [Data Layer troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html).

## Modules and addresses {#modules-and-addresses}

### Problem: A calibration module does not appear in the Data Layer {#faq-module-not-in-data-layer}

**Symptoms**

- There is no node `hdvisionsystems/lumiscan-calibration/<module name>` for a module you configured, and `hdvisionsystems/lumiscan-calibration/system/found-modules` does not list it.
- No module appears at all, or the application itself is missing from the Data Layer.

**Possible causes**

- The module configuration file is not listed under `modules` in `lumiscan-calibration.json`. A listed module appears even when its file cannot be loaded.
- The module is looked for under the wrong name. Its name is the name of its file without `.json`, in lower case. The `name` in the module’s `transform` block does not change it.
- `lumiscan-calibration.json` was changed, but the application was not restarted.
- `lumiscan-calibration.json` lists no module.
- The application stopped at start, for example because `lumiscan-calibration.json` is not valid JSON, or (ctrlX OS) because the licence is missing.

**Diagnostic procedure**

1. Read `hdvisionsystems/lumiscan-calibration/system/found-modules` - expected: the module’s name.
2. Check `modules` in `lumiscan-calibration.json` - expected: the module configuration file is listed.
3. Look for the module under the name of its file without `.json`, in lower case.
4. Read `hdvisionsystems/lumiscan-calibration/system/status-text` - expected: `"Initialized"`. Otherwise it says why the application serves no module, for example when `lumiscan-calibration.json` lists no module.
5. If the application itself is missing from the Data Layer, read the log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#general-logs)) - it says why the application stopped at start.

**Resolution**

- **If the file is not listed:** add the file name to the `modules` list of `lumiscan-calibration.json`, then restart LumiScan Calibration. See [Adding New Module](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/adding-new-module.html).
- **If you looked under the wrong name:** use the name of the file without `.json`, in lower case: `hdvisionsystems/lumiscan-calibration/<module name>`.
- **If `lumiscan-calibration.json` was changed without a restart:** restart LumiScan Calibration, for example with `hdvisionsystems/lumiscan-calibration/system/control/restart/execute`.
- **If the application stopped at start:** correct `lumiscan-calibration.json` as the log says, then start the application again. If the log names a missing licence, see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/requirements.html#licence).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information) to support, together with the content of `system/status-text` and `system/found-modules`, and `lumiscan-calibration.json`.

### Problem: Data Layer addresses under lumiscan-cam-calibration no longer work {#faq-data-layer-name}

**Symptoms**

Addresses that start with `hdvisionsystems/lumiscan-cam-calibration/…` no longer work.

**Possible causes**

- From v1.2.1, the application’s Data Layer name changed from `lumiscan-cam-calibration` to `lumiscan-calibration`.

**Diagnostic procedure**

1. Check the version of LumiScan Calibration - the change applies to v1.2.1 and later.
2. Check the addresses your program or PLC uses - expected: they start with `hdvisionsystems/lumiscan-calibration/`.

**Resolution**

- **If the addresses still use the old name:** update all addresses to `hdvisionsystems/lumiscan-calibration/…`. See [Release Notes: v1.2.1](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/release-notes/v1-2-1-2025-07-01.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information) to support, together with the addresses that do not work.

## Transforming points {#transforming-points}

### Problem: `transform/ready` stays `false`, and the status is -2 {#faq-transform-not-ready}

**Symptoms**

- `control/transform/ready` stays `false`.
- `control/status/code` is `-2` (`invalidSetting`).
- `control/transform/execute` answers `DL_INVALID_OPERATION_MODE`.
- A running stream publishes `NaN` for every point.

**Possible causes**

- The module has no lookup table: its module configuration file or the TIFF file it names could not be loaded, for example because the TIFF file is missing.
- The module configuration file has invalid or missing parameters, including its `stream` section. A malformed `stream` section is a malformed module file, for example stream mode without a source (`enable` set to `true` and no `address`), a step of another `kind`, or a key of a step written at the top of the section instead of in `onEntry`.
- The licence is not available. The status is then `-4` (`missingLicense`), and the module runs no function until the licence is back.

**Diagnostic procedure**

1. Read `control/status/code` - `-2`: a file could not be loaded; `-4`: the licence is missing.
2. Read the log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#general-logs)) - it says why the files could not be loaded, and names a malformed key.
3. Check that the TIFF file named by `relativePathToTiff` exists beside the module configuration file.
4. Check the module configuration file for invalid or missing parameters, including its `stream` section.

**Resolution**

- **If a file could not be loaded (status `-2`):** correct the files and reset the module. The module does not keep transforming with the old table, so that a corrected file is never mixed with an outdated one. See [Reloading the settings](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/functionalities.html#reset).
  1. Correct the module configuration file or the TIFF file.
  2. Reset the module (`control/reset`). No restart is needed.
  3. Check that `control/status/code` is `0` and `control/transform/ready` is `true`.
- **If the licence is missing (status `-4`):** install the licence `SWL-W-XCx-CALIBRATExHDVSx-V2NN`. On ctrlX OS, the application shuts down shortly after starting if the licence is missing. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/requirements.html#licence).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information) to support, together with the module configuration file, the name of its TIFF file and the log lines of the failed load.

### Problem: The application does not react to a request {#faq-request-not-detected}

**Symptoms**

After you set `XXX/control/<function name>/request` to `true`, `XXX/control/<function name>/ready` does not change to `false`, or the function does not run. `XXX` is `hdvisionsystems/lumiscan-calibration/<module name>`.

**Possible causes**

- More than one process writes the `request` node. The behaviour is then undefined, because the application can miss a request.
- `request` was not set back to `false`. The module waits for `request` to fall for as long as it takes.
- Your program uses another Data Layer version than the application.

**Diagnostic procedure**

1. Check which programs write `XXX/control/<function name>/request` - expected: only one process.
2. After setting `request` to `true`, read `ready` - expected: `false` (the module has seen the request).
3. After setting `request` back to `false`, read `ready` - expected: `true` again when the function has finished.
4. Check the Data Layer version your program uses - expected: the same as the application.

**Resolution**

- **If more than one process writes `request`:** make sure only one process accesses `XXX/control/<function name>/request` at a time. A program that cannot coordinate with others can use the `execute` method instead (`XXX/control/<function name>/execute`), which refuses a second call while one runs.
- **If `request` was not set back:** set `request` to `false` after `ready` has changed to `false`. See [Running a function](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/general-concept-of-handshake.html#functionality-execution).
- **If the Data Layer versions differ:** use the same Data Layer version as the application.

**If the problem persists**

Contact HD Vision Systems with the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information), together with the function you request and the values of `ready`, `request` and `control/status/code`.

### Problem: The transformed coordinates do not match the image {#faq-coordinates-wrong}

**Symptoms**

The transformed coordinates do not correspond to the expected positions.

**Possible causes**

- An axis is inverted.
- The required origin is not defined correctly. The calibration does not define the application-specific reference point automatically.
- Units are mixed, such as millimeters and pixels, in the application and connected systems.
- The configured TIFF file does not belong to the camera and calibrated plane in use.
- A point lies outside the lookup table. It gives a value from the edge of the table, without an error.

**Diagnostic procedure**

1. Move an object in a known direction and observe how the coordinates change - expected: each coordinate changes in the expected direction.
2. Check the reference point - expected: the origin your application needs is defined.
3. Check the units of the application and connected systems - expected: the same units throughout.
4. Check `relativePathToTiff` in the module configuration file - expected: the TIFF file for the camera and calibrated plane in use.
5. Check the input points - expected: within the image the lookup table was made for.

**Resolution**

- **If an axis is inverted:** a coordinate changes in the opposite direction. Send the observed and the expected direction to support (see [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information)).
- **If the reference point is not defined:** define the origin your application needs. The calibration does not do this automatically.
- **If units are mixed:** use consistent units throughout the application and connected systems.
- **If the wrong TIFF file is configured:** configure the TIFF file for the camera and calibrated plane in use, then reset the module (`control/reset`).
- **If points lie outside the lookup table:** keep the points within the image the table was made for.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information) to support, together with some input points, the coordinates you get and the coordinates you expect.

## Streams (experimental) {#streams-experimental}

### Problem: The stream does not start {#ts-stream-does-not-start}

**Symptoms**

`control/subscribe/output/stream/active` stays `false` after `control/subscribe/execute` was called with `control/subscribe/input/enable` set to `true`.

**Possible causes**

- `control/subscribe/input/address` is empty, or the queue size is not 1 to 4096: the call answers `DL_INVALID_VALUE` (ctrlX Data Layer) or `Rejected` (LumiScan Keryx).
- The module configuration file is malformed (status `-2`), for example a step of `stream.onEntry` the module does not have, or a key of a step written at the top of the `stream` section.
- A remap path does not fit the schema.
- The change could not be saved in the module configuration file: the call answers `DL_CREATION_FAILED`.
- The settings were edited on `system/settings`, and the application waits for a restart: the call answers `DL_RESOURCE_UNAVAILABLE`.
- The licence is missing. The stream runs only while the licence is present.

**Diagnostic procedure**

1. Check the answer of `control/subscribe/execute` - expected: `DL_OK`.
2. Check `control/status/code` - `-2`: the module configuration file is malformed; the log names the key.
3. Check `setting/stream/enable` and `setting/stream/address` - they show what the module applies.
4. Read the log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#general-logs)) - the module writes why the stream could not start, for example a remap path that does not fit the schema.

**Resolution**

- **If the address is empty or the queue size is out of range:** write the source’s folder to `control/subscribe/input/address`, or a queue size from 1 to 4096 to `control/subscribe/input/queue-size`, and call `control/subscribe/execute` again.
- **If the `stream` section is malformed or a remap path does not fit:** correct the `stream` section and reset the module. A failed start is retried after the reset, or after stream mode is switched off and on again with `control/subscribe/execute`. See [Configuring a stream](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/streams.html#configuring).
- **If the call answers `DL_CREATION_FAILED`:** the module configuration file could not be read or written. The answer and the log say why. Nothing changed.
- **If the call answers `DL_RESOURCE_UNAVAILABLE`:** restart the application, see [Status of the application and its modules](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#general-status).
- **If the licence is missing:** see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/requirements.html#licence).

A source the stream cannot subscribe to does not keep it from starting: it is tried again every 5 seconds, and the first failure is in the log. See [Problem: The stream runs, but no points arrive](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#ts-stream-no-points).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information) to support, together with the answer of `control/subscribe/execute`, the values of `setting/stream/enable` and `setting/stream/address`, and the `stream` section of the module configuration file.

### Problem: The stream runs, but no points arrive {#ts-stream-no-points}

**Symptoms**

`control/subscribe/output/stream/active` is `true`, but no points, or invalid points, arrive on `control/subscribe/output/stream/points` or `control/subscribe/output/stream/plain-points`.

**Possible causes**

- `received-updates` stays `0`: the source does not change, or `setting/stream/address` and the step’s `node` name another node than intended.
- `failed-updates` grows: the updates are not of the expected kind.
- `invalid-points` grows with `points`: the points lie outside the lookup table, or the module has no table (status `-2`).
- `skipped-updates` grows: the source updates faster than the module transforms.

**Diagnostic procedure**

1. Check the counters under `control/subscribe/output/stream/statistics` - expected: `received-updates` grows, and `failed-updates`, `invalid-points` and `skipped-updates` stay at `0`.
2. Compare `setting/stream/address` and the step’s `node` with the node you intend - expected: the node `node` in the folder `address`, exactly as written, including the case.
3. Read the log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#general-logs)) - it warns about an address that names the node twice, says when the source could not be subscribed to, and shows the first failed update.

**Resolution**

- **If `received-updates` stays `0`:** make the source change, or correct `address` and `node`. The module subscribes to the node `node` in the folder `address`, exactly as written, including the case. An address that still ends in the node names it twice. On the ctrlX Data Layer, an ordinary node such as a PLC array is read about every 100 ms, and changes in between are not seen; on LumiScan Keryx, writing the same values again is not an update. See [What a stream receives](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/streams.html#data-layers).
- **If `failed-updates` grows:** send updates of the expected kind. A plain stream needs a float32 or float64 array with a whole number of points; a remap stream needs a flatbuffer of the type its `schema` names.
- **If `invalid-points` grows:** keep the points within the lookup table, or, if the status is `-2`, follow [Problem: `transform/ready` stays `false`, and the status is -2](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#faq-transform-not-ready).
- **If `skipped-updates` grows:** reduce the source’s rate or the number of points per update. For short bursts, a larger queue size (`control/subscribe/input/queue-size`, saved as `queueSize`) helps. See [The queue](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/lumiscan-calibration/streams.html#queue).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-calibration/2.0.0/how-tos/troubleshooting.html#support-information) to support, together with the values of the counters under `control/subscribe/output/stream/statistics` and the `stream` section of the module configuration file.

## Information for support {#support-information}

If a problem persists, send the following to HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905. For licences, contact [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

- The version of LumiScan Calibration.
- The platform: ctrlX OS and its version on a ctrlX CORE or ctrlX IPC, or a PC with Windows 11 or Ubuntu 24.04 and LumiScan Keryx.
- The log: on ctrlX OS, the ctrlX OS system log (Logbook of the ctrlX web interface, or `journalctl`); on a PC, the console output of LumiScan Calibration.
- The date and time when the error occurred.
- The Data Layer status: `system/status-text`, `system/found-modules`, and for the affected module `control/status/code`, `control/status/text` and the result that an `execute` call answered.
- The configuration: `lumiscan-calibration.json` and the module configuration files, or the content of `hdvisionsystems/lumiscan-calibration/system/settings`, and the name of the TIFF file.