---
title: "Troubleshooting"
description: "Problems and error messages of LumiScan AI Object Matching - an inference that does not start or ends without a result, status codes 3, 100001, 100002 and -5, refused execute calls, and messages when reading results in ctrlX PLC Engineering."
product: "LumiScan AI Object Matching"
component: "lumiscan-ai-object-matching"
version: "2.1.0"
display_version: "2.1.0.9"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html"
---

# Troubleshooting – LumiScan AI Object Matching

This page starts with the general checks that apply to every problem. The problems follow, grouped into running inference and reading results in ctrlX PLC Engineering. Do the general checks first, then find your symptom.

## General checks {#general-checks}

- Read the status of the module: `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/code` and `hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/status/text`. The meaning of each code is listed in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#status-code-values).
- Read the status of the application: `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` and `hdvisionsystems/lumiscan-ai-object-matching/system/status-text`. If `restart-required` is `true`, see [Problem: Every module reports status -5 (restartRequired)](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#faq-restart-required).
- If a module did not start, read `hdvisionsystems/lumiscan-ai-object-matching/system/settings`. A module file that could not be read appears there as `{"$file": ..., "$error": ...}`; `"$error"` says why. See [What the node shows](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#what-the-node-shows).
- Read the log. On ctrlX OS, the application writes its messages to the ctrlX OS system log. Read them 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)).
- Check the licence. On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is in the system log. A missing licence is reported as status `-4` (`MissingLicense`). See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/requirements.html#licence).
- After you change a configuration file, restart the application. A change to the settings on the Data Layer also takes effect only with the next start.
- Problems that all LumiScan apps share - an app or module missing from the tree, a node that is "not found", a method call that is refused - are described in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html) of the LumiScan Keryx manual.

## Running inference

### Problem: inference/ready stays False, or the inference ends with status 100001 {#faq-no-new-external-image}

**Symptoms**

- `<network name>/control/inference/ready` stays `False`, so you cannot request an inference.
- `inference/ready` is `True`, but the request is never acknowledged: `ready` does not fall after you set `request` to `True`.
- `control/status/code` is `100001` (`ImageQueueEmpty`). Earlier versions reported status `10001` (`noNewExternalImage`); that code is no longer used.

**Possible causes**

- Status `100001`: the image could not be read. The image node (`input/image`, or the external image address) has no data, or could not be read. This is not an error.
- The application is still loading the configuration and setting up the network.
- The image stream of the module runs.
- No licence is installed.
- The settings were changed on the Data Layer, and the application waits for a restart (status `-5`).
- `ready` is `True`, but the request is not acknowledged: the last inference failed, and the module is in error. It ignores every request but `reset`.
- More than one process writes `control/inference/request`.

**Diagnostic procedure**

1. Read `control/status/code` and `control/status/text` of the module and look the code up in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#status-code-values):
   - `1` (`settingUp`): the module is still setting up.
   - `100001` (`ImageQueueEmpty`): the image could not be read.
   - `100002` (`StreamActive`): the image stream runs, see [Problem: An inference request is answered with status 100002 (StreamActive)](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#faq-stream-active).
   - `-4` (`MissingLicense`): the licence is missing.
   - `-5` (`restartRequired`): a restart is required, see [Problem: Every module reports status -5 (restartRequired)](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#faq-restart-required).
2. For status `100001`, check the image node. With an external image address (`externalImagePath` in the module configuration file), check that `<address>/data`, `<address>/height`, `<address>/width` and `<address>/pixel-type` (`Mono8` or `RGB8`) have values. Without one, check `hdvisionsystems/lumiscan-ai-object-matching/<network name>/input/image`.
3. Read `control/subscribe/output/stream/active`. Expected for inference on request: `false`.
4. If `ready` is `True` but does not fall after your request, read the log for a failed inference.
5. Check that only one process accesses `control/inference/request`.

**Resolution**

- **If the image could not be read (status `100001`):** provide an image from the image source, for example capture an image with the LumiScan Cam Driver, and run the inference again. For an image on `input/image`, write the raw image and set its width, height and pixel format, see [Initializing the Inference](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html). The application does not check whether the image is new: an image that has not changed since the last inference is inferred again.
- **If the module is still setting up:** wait until `inference/ready` is `True`.
- **If the image stream runs:** stop the stream first, see [Problem: An inference request is answered with status 100002 (StreamActive)](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#faq-stream-active).
- **If no licence is installed:** install the licence, see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/requirements.html#licence).
- **If a restart is required (status `-5`):** restart the application, see [Problem: Every module reports status -5 (restartRequired)](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#faq-restart-required).
- **If the module is in error after a failed inference:**
  1. Request `reset` (with the handshake on `control/reset/`, or with `control/reset/execute`).
  2. Check the application log for the cause.
  3. Request the inference again.
- **If more than one process writes `request`:** make sure that only one process accesses `control/inference/request` at a time. Otherwise the result of the handshake is undefined.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the values of `control/status/code`, `control/status/text`, `control/inference/ready` and `output/package-identifier`, and whether you use the handshake or `control/inference/execute`.

### Problem: status/code is 3 after every inference {#faq-status-3-after-inference}

**Symptoms**

After every inference requested through the handshake, `control/status/code` is `3` (`waitingForClient`), whether the inference succeeded or not.

**Possible causes**

- This is how the handshake works: an inference requested through the handshake ends at status `3`, whatever its outcome. `status/code` does not show whether it succeeded.

**Diagnostic procedure**

1. Before you request the inference, note the value of `<network name>/output/package-identifier`.
2. When `inference/ready` is `True` again, read `output/package-identifier` again. Expected: it has grown by one. It grows by one with every successful inference, and only then (see [Outcome of an Inference](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/general-concept-of-handshake.html#outcome-of-an-inference)).
3. If it did not grow, the inference failed. Request the next inference: if `inference/ready` does not fall, the module is in error after a failed inference.

**Resolution**

- **If `output/package-identifier` has grown by one:** the inference succeeded. Read the result at `<network name>/output/result`.
- **If it did not grow because the image could not be read (there was no image, or it was empty):** provide an image and request the inference again.
- **If it did not grow because the inference itself failed:** the module is in error and ignores every request but `reset`. Request `reset`, and check the application log for the cause.
- **If you want to read the outcome on `status/code` directly:** start the inference with `control/inference/execute` instead (from v2.1.0). `status/code` then keeps the outcome: `0`, `100001` or `-1`. See [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#execute-a-method).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the value of `output/package-identifier` before and after the inference.

### Problem: A write to execute is refused {#faq-execute-refused}

**Symptoms**

From v2.1.0. A write to `<network name>/control/<function>/execute` is answered with one of the following results. The function does not run; a refused write is never queued.

| ctrlX Data Layer | LumiScan Keryx |
| --- | --- |
| `DL_TOO_MANY_OPERATIONS` | `TooManyOperations` |
| `DL_INVALID_OPERATION_MODE` | `InvalidOperationMode` |
| `DL_RESOURCE_UNAVAILABLE` | `ResourceUnavailable` |

**Possible causes**

- `DL_TOO_MANY_OPERATIONS` / `TooManyOperations`: another function of the module runs, through the handshake or another `execute`.
- `DL_INVALID_OPERATION_MODE` / `InvalidOperationMode`: the `ready` signal of the function is `False`, so the module cannot run it - for example `inference` while the image stream runs.
- `DL_RESOURCE_UNAVAILABLE` / `ResourceUnavailable`: the application is shutting down; or the settings were changed on the Data Layer and a restart is required (status `-5`); or the module is in error after a failed inference. `reset/execute` is never refused for the error.

**Diagnostic procedure**

1. Note the exact result of the write, and look it up in [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/initializing-the-inference.html#execute-a-method) (see also [A method call is refused](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#refused) in the LumiScan Keryx manual).
2. For `DL_INVALID_OPERATION_MODE` / `InvalidOperationMode`: read the `ready` node of the function (for an inference, `control/inference/ready`) and `control/status/code`. Read `control/subscribe/output/stream/active`: `true` means the image stream runs.
3. For `DL_RESOURCE_UNAVAILABLE` / `ResourceUnavailable`: read `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required`. `true` means a restart is required.
4. Read the log. The apps log the first refusal of a method, then at most one line every ten seconds for the same method and result.

**Resolution**

- **If another function runs (`DL_TOO_MANY_OPERATIONS` / `TooManyOperations`):** retry. The write succeeds once that operation finishes.
- **If the `ready` signal is `False` (`DL_INVALID_OPERATION_MODE` / `InvalidOperationMode`):** bring the module into the required state first; retrying alone keeps failing. Do not retry in a loop. If the image stream runs, stop it first, see [Problem: An inference request is answered with status 100002 (StreamActive)](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#faq-stream-active).
- **If a restart is required:** restart the application, see [Problem: Every module reports status -5 (restartRequired)](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#faq-restart-required).
- **If the module is in error after a failed inference:** run `reset` (`control/reset/execute`), then retry.
- **If the application is shutting down:** the function cannot run. When the application has started again, its nodes can be read again; then retry.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the exact result of the write, the function you called and the value of `control/status/code`.

### Problem: An inference request is answered with status 100002 (StreamActive) {#faq-stream-active}

**Symptoms**

From v2.2.0 (image stream, experimental).

- After a request on `control/inference/request`, `control/status/code` is `100002` (`StreamActive`), and the request is not acknowledged.
- `control/inference/ready` is `False`.
- `control/inference/execute` answers `DL_INVALID_OPERATION_MODE` (LumiScan Keryx: `InvalidOperationMode`).

**Possible causes**

- The module infers on its image stream. The stream and inference on request use the same network, so they never run at the same time (see [Inference on request while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/inference-on-an-image-stream.html#while-streaming)). This is not an error, and no reset is needed.
- The module started in stream mode: `stream.enable` is `true` in the module configuration file. `control/subscribe/execute` saves `enable`, so after a restart the module starts its stream again at once.

**Diagnostic procedure**

1. Read `control/subscribe/output/stream/active`. `true` means the module infers on its image stream.
2. Read `setting/stream/enable` and `setting/stream/address`: they show what the module applies now, as saved in the `stream` section of the module configuration file.

**Resolution**

- **If you need inference on request:**
  1. Stop the stream: write `false` to `control/subscribe/input/enable` and `true` to `control/subscribe/execute`. This is saved: the module starts again as it was left.
  2. Check that `control/subscribe/output/stream/active` is `false` and `control/inference/ready` is `True`.
  3. Request the inference.
- **If you need the results of the stream:** subscribe to `control/subscribe/output/stream/result` and read the results there.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the values of `control/subscribe/output/stream/active` and `setting/stream/enable`, and the `stream` section of the module configuration file.

### Problem: Every module reports status -5 (restartRequired) {#faq-restart-required}

**Symptoms**

- Every module reports status `-5` (`restartRequired`). It answers no request, and its `ready` signals are `false`.
- `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` is `true`.
- Every `execute` method of a module answers `DL_RESOURCE_UNAVAILABLE` / `ResourceUnavailable`. That includes `reset`.
- A running image stream stops.
- The log has the message at error level.

**Possible causes**

- The settings were changed on the Data Layer (`hdvisionsystems/lumiscan-ai-object-matching/system/settings`). The change is saved, but takes effect only with the next start (see [Restart required](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/settings-on-the-data-layer.html#restart-required)).
- `activate-module` or `deactivate-module` was called. The change applies from the next start.
- A file could not be saved: the write answered `DL_CREATION_FAILED` / `CreationFailed`. Files changed before it stay changed, so the application requires a restart all the same.

**Diagnostic procedure**

1. Read `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required`. Expected in this state: `true`.
2. Read `hdvisionsystems/lumiscan-ai-object-matching/system/status-text`. It says which files changed.
3. Read `hdvisionsystems/lumiscan-ai-object-matching/system/settings`. It shows the files as saved, which is what the next start loads.
4. If a write to `settings` answered `DL_CREATION_FAILED` / `CreationFailed`, read the log for the file that could not be saved.

**Resolution**

A reset does not end this state; only a restart does.

- **If the settings were changed on the Data Layer, or a module was activated or deactivated:**
  1. Call `hdvisionsystems/lumiscan-ai-object-matching/system/control/restart/execute`. It answers `DL_OK` / `Ok` as soon as the restart has begun. On ctrlX OS, ctrlX OS starts the application again after about five seconds.
  2. Wait until `hdvisionsystems/lumiscan-ai-object-matching/system/restart-required` can be read again. Expected: `false`.
- **If a file could not be saved (`DL_CREATION_FAILED` / `CreationFailed`):** correct the files, then restart the application as described above.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the content of `system/status-text` and `system/settings`.

## Reading results in ctrlX PLC Engineering

### Problem: The schemas folder does not exist {#faq-schemas-folder-missing}

**Symptoms**

On ctrlX OS, in **Manage app data**, the folder `lumiscan-ai-object-matching/schemas` does not exist, so you cannot download `object_detection.fbs` from `lumiscan-ai-object-matching/schemas/flatbuffers`.

**Possible causes**

- The application has not started successfully. The `schemas` folder is created during start-up, after the licence check.
- The licence is missing. The application then shuts down shortly after starting.

**Diagnostic procedure**

1. Read the ctrlX OS system log in the Logbook of the ctrlX web interface, or with `journalctl`. If the licence is missing, the reason is written there.
2. Check that the ctrlX licence `SWL-W-XCx-OBJxMATCHxHDVSx-V2NN` is installed.

**Resolution**

- **If the licence is missing:** install a valid licence, see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/requirements.html#licence) and [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/troubleshooting.html) of the LumiScan Licensing manual. Then check in **Manage app data** that the folder `lumiscan-ai-object-matching/schemas/flatbuffers` exists.
- **If the application did not start for another reason:** the reason is in the system log. Contact support.

Do not edit files in `schemas`: the application deletes and recreates the folder on every start.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the messages of the application from the ctrlX OS system log.

### Problem: Import from FlatBuffers file… is not in the context menu {#ts-import-command-missing}

**Symptoms**

In ctrlX PLC Engineering, you right-click **Application** in the device tree. The context menu does not contain **Import from FlatBuffers file…**.

**Possible causes**

- The ctrlX Data Layer library `CXA_Datalayer` is missing.

**Diagnostic procedure**

1. Check that you use ctrlX PLC Engineering 2.6 or later.
2. Check in the **Library Manager** of the PLC project that `CXA_Datalayer` and `CXA_Flatbuffers` are referenced.

**Resolution**

- **If the ctrlX Data Layer library is missing:**
  1. In the PLC Engineering menu bar, select **Tools** > **Library Repository…**.

  2. Search for `CXA_Datalayer`, select the library and click **Open**.

  3. Repeat the import: right-click **Application**, select **Import from FlatBuffers file…** and select `object_detection.fbs`.

     The screenshots are in [Install the ctrlX Data Layer Library](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-install-datalayer-library).

- **If another library is missing after the import:** add it in the **Library Manager**.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the version of ctrlX PLC Engineering and the libraries listed in the **Library Manager**.

### Problem: The message "Identifier 'VectorT' not defined" appears after the import {#faq-vectort-not-defined}

**Symptoms**

After the import of `object_detection.fbs`, the editor of the function block `hdv_object_detection2d_InstanceTVec` shows the message `Identifier 'VectorT' not defined` (observed with ctrlX PLC Engineering 3.6).

![Editor of hdv_object_detection2d_InstanceTVec with the message Identifier 'VectorT' not defined on the line FUNCTION_BLOCK hdv_object_detection2d_InstanceTVec EXTENDS flatbuffers.VectorT](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/_images/plc-vectort-not-defined.png)

*Figure 1. Message in the editor of hdv_object_detection2d_InstanceTVec*

**Possible causes**

- The function block `hdv_object_detection2d_InstanceTVec` extends `flatbuffers.VectorT`. The version of the `CXA_Flatbuffers` library that is available for ctrlX PLC Engineering 3.6 (0.1.3.3) does not contain this function block.

**Diagnostic procedure**

1. Open the editor of `hdv_object_detection2d_InstanceTVec`. Expected: the message is shown on the line `FUNCTION_BLOCK hdv_object_detection2d_InstanceTVec EXTENDS flatbuffers.VectorT`.
2. Check which version of `CXA_Flatbuffers` the PLC project references in the **Library Manager**.

**Resolution**

The message does not affect reading results.

- **If the message is shown:**
  - Do not use `hdv_object_detection2d_InstanceTVec` in your program. It is not needed to read results. Access individual instances with `getInstances` of `hdv_object_detection2d_Result`, see [Example: Reading Position and Score of an Instance](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/lumiscan-ai-object-matching/accessing-flatbuffers-data.html#lumiscan-example-instance).
  - If the message is disturbing, delete the function block `hdv_object_detection2d_InstanceTVec` from the application. No other generated function block refers to it.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-ai-object-matching/2.1.0/troubleshooting.html#support-information) to support, together with the version of ctrlX PLC Engineering, the version of `CXA_Flatbuffers` and the exact message.

## Information for support {#support-information}

If a problem persists, send the following information to support:

- The version of LumiScan AI Object Matching.
- The platform: ctrlX OS on a ctrlX CORE or ctrlX IPC, with the ctrlX OS version (with TPU acceleration, also the version of App Hardware Support); or a PC with Windows 11 or Ubuntu 24.04 and LumiScan Keryx.
- For problems in ctrlX PLC Engineering: the version of ctrlX PLC Engineering and of the libraries `CXA_Datalayer` and `CXA_Flatbuffers`.
- The log of the application. On ctrlX OS, the messages of the application from the ctrlX OS system log (Logbook of the ctrlX web interface, or `journalctl`). On a PC, the log of the application.
- The date and time of the error.
- The Data Layer status: which Data Layer you use (ctrlX Data Layer or LumiScan Keryx; on a PC, the Data Layer address), the values of `control/status/code` and `control/status/text` of the module, `system/restart-required` and `system/status-text`, and, for a refused method call, the exact result of the write.
- The configuration files from the folder `lumiscan-ai-object-matching`: the application configuration file `ai-object-matching.json`, the module configuration file and the model description file (`.json`) in `models`. Alternatively, send the content of `hdvisionsystems/lumiscan-ai-object-matching/system/settings`: every value named `password` shows there as `"***"`.

Contact 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).