---
title: "Troubleshooting"
description: "Troubleshooting the Data Layer of the LumiScan apps - general checks, the broker, missing apps, modules and nodes, refused method calls, handshakes, streams, the OPC UA Connector, and what to send to support."
product: "LumiScan Keryx"
component: "lumiscan-keryx"
version: "1.0.0"
display_version: "1.0.0.7"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html"
---

# Troubleshooting – LumiScan Keryx

Start with the [General checks](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#general-checks): they help with every Data Layer problem. Then find your symptom in the sections below and work through its steps in order. The last section lists what to send to support if the problem persists.

## General checks {#general-checks}

Check these points first:

- **The app runs and is on the Data Layer.** On a PC, open the Keryx page `http://127.0.0.1:7555/` (Windows) or run `krxclient tree hdvisionsystems --depth 1`: the tree shows the folder `hdvisionsystems` with one folder per running app. On ctrlX OS, use the Data Layer view of the ctrlX OS web interface. See [Tools](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/tools.html).

- **All programs use the same broker (PC).** Each app names the broker address it uses in its log at start. Every app, Cockpit and the OPC UA Connector must use the same address. The default is `tcp://127.0.0.1:5555`; `--keryx-url` or `LUMISCAN_KERYX_URL` changes it. See [Options and environment variables](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html#options).

- **The app serves its modules.** For each app that has modules, `hdvisionsystems/<app>/system/found-modules` lists them. If the list is empty, `hdvisionsystems/<app>/system/status-text` says why.

- **The status of the module.** The Cam Driver, AI Object Matching and Calibration report it on `<module>/control/status/code` and `control/status/text`: values below `0` are errors. The finders report each method on `<method>/output/status-code` and `status-text`. Use the numbers, not the texts. See [Status Codes and Results](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html).

- **The addresses match the app version.** Addresses are lower case. Several nodes moved in the upcoming releases without an alias at the old address: compare your program with the **Data Layer Reference** of the app version you run.

- **The logs.** The apps log the first refusal of a method, then at most one line every ten seconds for the same method and result.

  | Log | Where |
  | --- | --- |
  | An app on ctrlX OS | the ctrlX OS system log: the Logbook of the ctrlX web interface, or `journalctl` |
  | The broker on Windows (log, records and `broker.json`) | `C:\ProgramData\HD Vision Systems GmbH\LumiScan Keryx` |
  | The broker on Ubuntu | `/tmp/lumiscan-keryx` |
  | LumiScan Keryx Utilities | `%LOCALAPPDATA%\LumiScan Keryx Utilities\logs\keryx-utilities.log` |

## Broker, apps and nodes {#broker-apps-nodes}

### Problem: An app waits for the broker (PC) {#no-broker}

**Symptoms**

An app on a PC logs that it could not reach a Data Layer broker (`could not reach a Keryx broker`), and waits.

**Possible causes**

- It is the first start: the broker takes a few seconds to answer.
- **LumiScan Keryx** is not installed.
- The terminal was opened before LumiScan Keryx was installed. The installer sets the variables `HDV_KERYX_BROKER` and `HDV_KERYX_PAGE`; a program or terminal that was already open does not see them.
- The automatic start is switched off: `--no-keryx-autostart` or `LUMISCAN_KERYX_AUTOSTART=0`.
- The broker was stopped with **Shut down broker** on the Keryx page.
- The address is an `ipc://` address relative to a folder: no app starts a broker for it.
- The address is that of another computer: an app only connects to it and never starts a broker there.

**Diagnostic procedure**

1. Wait a few seconds after the first start - expected: the app connects as soon as the broker answers.
2. Read the broker address in the app’s log at start - expected: the address you intend to use, by default `tcp://127.0.0.1:5555`.
3. Check that LumiScan Keryx is installed, and that you opened the terminal after its installation.
4. Check the options and environment variables of the app - expected: neither `--no-keryx-autostart` nor `LUMISCAN_KERYX_AUTOSTART=0` is set, unless you start the broker yourself.
5. Check whether someone clicked **Shut down broker** on the Keryx page. After that, the apps do not start the broker again by themselves.
6. With an `ipc://` address: check that the broker and every app were started from the same folder.

**Resolution**

- **If it is the first start:** wait. The app connects as soon as the broker answers.

- **If LumiScan Keryx is not installed:**

  a. Install LumiScan Keryx first, then the apps. Run each installer as administrator.

  b. Open a **new** terminal and start the app again.

- **If the terminal was opened before the installation:** open a new terminal and start the app again.

- **If the automatic start is switched off:** remove the option or the variable, or start the broker yourself: `krxsystem --backend hdv --url <address>`.

- **If the broker was shut down:** click **Start broker** on the Keryx page, or open the LumiScan Keryx window. Starting a `krxsystem` by hand or restarting the PC also starts it again.

- **If the address is a relative `ipc://` address:** start the broker yourself (`krxsystem --backend hdv --url <address>`), then start every app from that same folder.

- **If the address is that of another computer:** running apps on several PCs against one broker is not covered by this manual. Contact support.

See [LumiScan Keryx on a PC](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the message from the app’s log, the broker address the app names there, and the broker log.

### Problem: An app or a module is missing from the tree {#app-missing}

**Symptoms**

The tree has no folder for the app under `hdvisionsystems`, or a module you expect does not appear on the Data Layer: `hdvisionsystems/<app>/system/found-modules` does not list it.

**Possible causes**

- The app is not running.
- The app uses another broker than the program you look with (PC).
- The settings file could not be loaded.
- The licence is missing. On ctrlX OS, an app without a valid licence stops shortly after it starts.
- The module name contains capital letters or other characters than `a-z`, `0-9`, `-` and `_`. The Cam Driver and AI Object Matching refuse such a module.
- Cam Driver, AI Object Matching, Calibration: the module file was activated with `system/control/activate-module/execute`, but the app has not restarted since.
- Template Finder, Object Finder, Area Detector, Text Reader: the module was made with `system/create-module/execute` and not saved, and the app has restarted since.

**Diagnostic procedure**

1. Check the tree - on a PC on the Keryx page or with `krxclient tree`; on ctrlX OS in the ctrlX OS web interface; expected: the folder `hdvisionsystems` holds one folder per running app.
2. On a PC, compare the broker address in the app’s log with the address of Cockpit, the OPC UA Connector or the tool you use - expected: the same address.
3. Read `hdvisionsystems/<app>/system/found-modules` - expected: it lists the module.
4. If it does not, read `hdvisionsystems/<app>/system/status-text` - expected: it says why the app serves no module, most often a settings file that could not be loaded, or a missing licence.
5. Check the module name - expected: only lower-case letters, digits, `-` and `_`. The name comes from `id` in the module file (Cam Driver), from `name` in the module file (AI Object Matching), from the module file’s name (Calibration), or from the module id (the finders). See [Module names](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/addresses.html#module-names).
6. On ctrlX OS, read the system log - expected: no message that the licence is missing.

**Resolution**

- **If the app is not running:** start it, and wait until it has finished starting.

- **If the app uses another broker:** pass the same `--keryx-url` to every app, to Cockpit and to the OPC UA Connector.

- **If the settings file could not be loaded:** correct it, and start the app again. On a PC, the settings are files in the app’s settings folder (on Windows `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\<program>\etc\<settings folder>`); the option `--generate-settings` writes an example. See [Where the files are](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html#files). On ctrlX OS, upload them as the app’s manual describes under **Uploading Data**.

- **If the licence is missing:** see [LumiScan Licensing](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/index.html).

- **If the module name is not valid:** use lower-case module names.

- **If the app has not restarted since the activation:** call `hdvisionsystems/<app>/system/control/restart/execute`.

- **If a finder module was not saved:**

  a. Make the module again with `system/create-module/execute`.

  b. Save the module list with `system/save-current-modules/execute` and the module’s inputs with `system/save-module-inputs/execute`.

See [Settings, Modules and Restart](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/settings-and-modules.html).

**If the problem persists**

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

### Problem: A node is "not found" {#node-not-found}

**Symptoms**

A read, write or call answers that the node was not found: `NodeNotFound` (LumiScan Keryx), `DL_INVALID_ADDRESS` (ctrlX Data Layer) or `BadNodeIdUnknown` (OPC UA). A program written for an earlier release no longer finds a node it used.

**Possible causes**

- The case or spelling of the address is wrong. Addresses are lower case.
- The node moved. Several nodes moved in the upcoming releases without an alias at the old address, for example the Cam Driver’s stream from `input/stream/enable` to `control/publish/input/enable`.
- The app is restarting: its nodes disappear until it is up again.
- The module is missing, see [Problem: An app or a module is missing from the tree](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#app-missing).

**Diagnostic procedure**

1. Compare the address with the tree - on a PC on the Keryx page or from `krxclient tree`; on ctrlX OS in the ctrlX OS web interface; expected: the same case and spelling.
2. Compare the address with the **Data Layer Reference** of the app version you run - expected: the node is listed there at this address.
3. Check whether the app is restarting - expected: `system/restart-required` can be read.

**Resolution**

- **If the case or spelling is wrong:** correct the address.
- **If the node moved:** change your program to the address in the **Data Layer Reference** of the app version you run.
- **If the app is restarting:** wait until `system/restart-required` can be read again.
- **If the module is missing:** see [Problem: An app or a module is missing from the tree](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#app-missing).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the address that is not found and the result of the call.

## Calling functions {#calling-functions}

### Problem: A method call is refused {#refused}

**Symptoms**

A write to an `execute` node does not answer `Ok` (`DL_OK`, OPC UA `Good`), but one of the results in [Results of a method call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#method-results), for example `TooManyOperations`, `InvalidOperationMode`, `ResourceUnavailable` or `Rejected`. On the ctrlX Data Layer, a refused call carries no reason.

**Possible causes**

- `TooManyOperations` (ctrlX `DL_TOO_MANY_OPERATIONS`, OPC UA `BadTooManyOperations`): another operation of the same module runs - an execute, a handshake, or in the finders a frame of a stream.
- `InvalidOperationMode` (ctrlX `DL_INVALID_OPERATION_MODE`, OPC UA `BadInvalidState`): the function is not ready. Its `ready` is `false`, for example because there is no licence, the camera is not connected, or a stream runs.
- `ResourceUnavailable` (ctrlX `DL_RESOURCE_UNAVAILABLE`, OPC UA `BadResourceUnavailable`): a restart is required after a change through `system/settings` (status `-5`), the app is stopping, or an AI module is in error.
- `Rejected` (ctrlX `DL_INVALID_VALUE`, OPC UA `BadRequestNotAllowed`): an input is not valid; nothing changed.
- `NodeNotFound` (ctrlX `DL_INVALID_ADDRESS`, OPC UA `BadNodeIdUnknown`): an image, a source, a module or the node itself was not found.
- `CreationFailed` (ctrlX `DL_CREATION_FAILED`): something could not be written or made, for example a file, an existing module or an unavailable licence.
- `InternalError` (ctrlX `DL_FAILED`, OPC UA `BadInternalError`): the operation failed.

**Diagnostic procedure**

1. Note the result of the call, and look it up in [Results of a method call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#method-results).
2. Read the app’s log - expected: the reason of the refusal. The apps write it there because a refused call on the ctrlX Data Layer carries none.
3. Cam Driver, AI Object Matching, Calibration: read `control/<function>/ready` together with `control/status/code` and `control/status/text`. `ready` names the missing precondition; the status text still carries the message of the fault that caused it.
4. Finders: read `<method>/output/status-code` and `status-text`. See [Execution status of the finders](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#execution-status).

**Resolution**

- **If another operation of the module runs (`TooManyOperations`):** retry. The same call succeeds once the running operation has finished.
- **If the function is not ready (`InvalidOperationMode`):** bring the module into the required state first, for example connect the camera. Retrying alone keeps failing: do not retry in a loop. The Cam Driver’s `capture` and AI Object Matching’s `inference` are not ready while their stream runs: stop the stream first, see [Streams and single operations](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html#collisions). The app’s manual says when each `ready` is `true`.
- **If a restart is required (`ResourceUnavailable`, status `-5`):** see [Problem: Status `-5` (`restartRequired`), or `ResourceUnavailable` on every call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#faq-restart-required).
- **If the app is stopping or an AI module is in error (`ResourceUnavailable`):** read the status, and restart the app when required.
- **If an input is not valid (`Rejected`):** correct the input and call again.
- **If something was not found (`NodeNotFound`):** check the address and its case, see [Problem: A node is "not found"](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#node-not-found).
- **If something could not be written or made (`CreationFailed`), or the operation failed (`InternalError`):** read the log and the status; they say why.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the address of the method, its result, the values of `ready`, `control/status/code` and `control/status/text`, and the log lines about the refusal.

### Problem: Status `-5` (`restartRequired`), or `ResourceUnavailable` on every call {#faq-restart-required}

**Symptoms**

Every module of the app reports `control/status/code` = `-5` (`restartRequired`), and its methods answer `ResourceUnavailable` (ctrlX `DL_RESOURCE_UNAVAILABLE`, OPC UA `BadResourceUnavailable`).

**Possible causes**

- The settings were changed through `system/settings`. They apply at the next start.

**Diagnostic procedure**

1. Read `hdvisionsystems/<app>/system/restart-required` - expected after a saved change: `true`, until the app restarts.

**Resolution**

- **If the settings were changed through `system/settings`:**

  a. Call `hdvisionsystems/<app>/system/control/restart/execute`. The app’s nodes disappear until it is up.

  b. Wait until `system/restart-required` can be read again.

  c. Run your start-up sequence again: values written to `input/` are not kept, the camera is not connected, and the Cam Driver’s stream is off. See [What is kept across a restart](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/settings-and-modules.html#kept).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the value of `system/restart-required` and the content of `system/settings`.

### Problem: The execute call answers `Ok` (`DL_OK`), but nothing happened {#faq-write-ok-but-failed}

**Symptoms**

Cam Driver, AI Object Matching, Calibration: a write to an `execute` node answers `Ok` (`DL_OK`, OPC UA `Good`), but the operation had no effect.

**Possible causes**

- The operation ran but failed. The result of the write only says that the operation ran. Whether it succeeded is in the module status.

**Diagnostic procedure**

1. Read `control/status/code` and `control/status/text` right after the call - expected: `0` (`ready`). Values below `0` are errors.
2. Look up the code in [Module status](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#module-status). App-specific codes are listed in each app’s manual.

**Resolution**

- **If the status is below `0`:** remove the cause the code names, for example correct an input (`-3`, `invalidInput`), or restart the app (`-5`, see [Problem: Status `-5` (`restartRequired`), or `ResourceUnavailable` on every call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#faq-restart-required)). Then call again.
- In your program, always read `control/status/code` after the call. See [Where the inputs, outputs and outcome are](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/execute.html#where).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the address of the method and the values of `control/status/code` and `control/status/text` after the call.

### Problem: A handshake does not finish, or shows the wrong outcome {#handshake-stuck}

**Symptoms**

`ready` stays `false` after the request; a Cam Driver `capture` or an AI Object Matching `inference` by handshake ends at status `3` (`waitingForClient`); or a failed Cam Driver `connect-camera` shows its error for about 100 ms only.

**Possible causes**

- `request` is still `true`: the module waits for `request` to fall, for as long as it takes.
- Two programs write the same `request` node, and a request is lost.
- Cam Driver `capture`: a failed capture ends at status `3`, not at its own error code, and `capture/ready` stays `false` until a `reset` succeeds. A failed `reset`, `save` or `load` also stays until a `reset` succeeds.
- AI Object Matching `inference`: every inference ends at status `3` whatever its outcome. After a failed inference, and while the module has an error, every request but `reset` is ignored. While the stream runs, `inference/ready` is `false` and a request gets status `100002`.
- Cam Driver: any other error stays on the status for about 100 ms only.
- Cam Driver without a licence: every `ready` is `false` and the status is `-4`.

**Diagnostic procedure**

1. Follow the steps in [The sequence](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html#sequence), polling at 50 to 100 ms, and note the step at which it stops.
2. Read `request` after `ready` has become `false` - expected: your program has set it back to `false`.
3. Check which programs write the `request` node - expected: only one.
4. For a Cam Driver `capture` or an AI Object Matching `inference`: read `output/package-identifier` before and after - expected: it has grown by one when the operation succeeded.
5. For a Cam Driver `connect-camera`: read `device-info/is-connected` - expected: `true` when the camera is connected.
6. For the Cam Driver: read `control/status/code` - expected: not `-4`.

**Resolution**

- **If `request` is still `true`:** set `request` to `false`.
- **If two programs write `request`:** let only one program write it. A program that cannot coordinate with others uses the [execute method](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/execute.html), which refuses a second call while one runs.
- **If a `capture` or an `inference` ends at status `3`:** this is how they end. Use `output/package-identifier` to tell success, or use the execute method: the status then keeps the operation’s own code. After a failed capture, run `reset`.
- **If AI Object Matching ignores requests after a failed inference:** run `reset`; it runs at once.
- **If the AI Object Matching stream runs (status `100002`):** stop the stream first.
- **If a Cam Driver error disappears from the status after about 100 ms:** check a connection with `device-info/is-connected`, not with the status.
- **If the Cam Driver has no licence (status `-4`):** see [LumiScan Licensing](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/index.html).

See [How the apps differ](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html#differences).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the function, the step at which the handshake stops, and the values of `ready`, `request`, `control/status/code` and `output/package-identifier`.

## Streams {#streams}

### Problem: A stream delivers nothing {#stream-nothing}

**Symptoms**

No results arrive from a stream: `output/stream/active` stays `false`, or the counters under `…/stream/statistics/` stop growing. After a restart no images arrive.

**Possible causes**

- The inputs were written, but `execute` was not called. The inputs take effect only on `execute`; writing `enable` alone starts nothing.
- `enable` is `true` without an address. The call is refused (`Rejected`, ctrlX `DL_INVALID_VALUE`), and nothing changes.
- The consumer’s `address` is not the producer’s stream folder.
- The module cannot run: licence, network not loaded, or restart required.
- The Cam Driver restarted: its stream and the camera connection are not kept across a restart.
- `connect-camera`, `disconnect-camera` or `reset` stopped the Cam Driver’s stream.
- Nothing triggers the camera. The Cam Driver never triggers the camera by itself.
- Calibration: its `stream` section has no `onEntry` step that says how to read the source.

**Diagnostic procedure**

1. On the camera, read `control/publish/output/stream/active` - expected: `true`.

2. On the consumer, read `control/subscribe/output/stream/active` - expected: `true`.

3. On the consumer, read `setting/stream/…` - expected: `enable` is `true`, and `address` is the producer’s stream folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`.

4. Follow the chain with the counters under `…/stream/statistics/` - expected: they grow. The first counter that does not grow shows where the chain stops. See [Following the chain](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html#counters).

   a. The Cam Driver counts no `frames`: nothing triggers the camera.

   b. Calibration: `failed-updates` grows and no points appear: the `onEntry` step is missing.

   c. Finders and code readers: `control/subscribe/output/stream/last-failure` says why the last item failed.

5. Read `control/status/code` and the log of the module that stops the chain.

**Resolution**

- **If `execute` was not called:** after writing the inputs, call `control/subscribe/execute` (a consumer) or `control/publish/execute` (the Cam Driver). Then wait until `output/stream/active` is `true`.

- **If `enable` is `true` without an address:** write `control/subscribe/input/address`, then call `control/subscribe/execute`.

- **If the address is not the producer’s stream folder:** write the folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, and call `execute`.

- **If the module cannot run:** remove the cause that `control/status/code` and the log name. For a required restart, see [Problem: Status `-5` (`restartRequired`), or `ResourceUnavailable` on every call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#faq-restart-required).

- **If the Cam Driver restarted, or the stream was stopped by `connect-camera`, `disconnect-camera` or `reset`:**

  a. Run the `connect-camera` handshake.

  b. Call `control/publish/execute` with `enable` = `true`.

  c. The consumers subscribe again by themselves.

- **If nothing triggers the camera:** check its trigger mode, or call `control/trigger/execute`.

- **If the Calibration `onEntry` step is missing:** add it to the `stream` section. See the Calibration manual.

See [Starting and stopping a stream](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html#running).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the values of `output/stream/active`, `setting/stream/…` and the counters under `…/stream/statistics/` of every module in the chain.

### Problem: Stream results are old or mixed {#ts-stream-results-mixed}

**Symptoms**

The results your program reads are old, or values of different results are mixed.

**Possible causes**

- Your program read while a new result was written.

**Diagnostic procedure**

1. Check how your program reads the plain output nodes - expected: it reads them after `output/package-identifier` has changed. `output/package-identifier` is written last.

**Resolution**

- **If your program reads while a new result is written:** read the outputs when `output/package-identifier` changes, or subscribe to a single node such as Calibration’s `plain-points`. See [Keep latest output](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html#keep-latest).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the nodes your program reads and in which order.

## OPC UA Connector {#opc-ua}

### Problem: An OPC UA client cannot connect {#ts-opcua-cannot-connect}

**Symptoms**

The client cannot connect to `opc.tcp://<pc>:4840`.

**Possible causes**

- The connector does not run: it was started before the broker and ended, see [Problem: The connector window closes at once](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#ts-opcua-window-closes).
- The PC’s firewall blocks TCP port 4840.
- The client insists on a secure channel. The connector supports security policy **None** and anonymous login only.
- The connector was started on another port (`--port`).

**Diagnostic procedure**

1. Check that the connector runs - expected: its window is open.
2. Check the PC’s firewall - expected: TCP 4840 is open for the address of the PLC or client.
3. Check the client’s security settings - expected: security policy **None**, anonymous login.
4. Check the connector’s options - expected: the port the client uses.

**Resolution**

- **If the connector does not run:** start the apps first, then the connector.
- **If the firewall blocks the port:** open TCP 4840 for the PLC’s address only.
- **If the client insists on a secure channel:** set it to security policy **None** and anonymous login. Certificates, user names and encryption are not supported. See [Security](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/opc-ua.html#security).
- **If the connector runs on another port:** connect to that port.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the connector’s options, its log, and the error message of the client.

### Problem: The connector window closes at once {#ts-opcua-window-closes}

**Symptoms**

The window of the OPC UA Connector closes right after its start; the connector ends with exit code 1.

**Possible causes**

- No broker runs. The connector never starts a broker: without one it logs the reason and ends.
- The connector’s `--keryx-url` names another broker than the apps use.

**Diagnostic procedure**

1. Check that the apps run - expected: the Keryx page shows `hdvisionsystems` with the apps.
2. Compare `--keryx-url` of the connector with the broker address the apps name in their logs - expected: the same address.
3. Read the connector’s log - expected: the reason why it ended.

**Resolution**

- **If no broker runs:** start the apps first, then the connector.
- **If the connector uses another address:** pass it the same `--keryx-url` as the apps.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the connector’s options and its log.

### Problem: `Objects` is empty or has no `hdvisionsystems` {#ts-opcua-objects-empty}

**Symptoms**

The client is connected, but `Objects` is empty or does not hold `hdvisionsystems`.

**Possible causes**

- The apps are not running.
- The connector’s `--keryx-url` names another broker than the apps use.
- An app started only recently: the connector walks the tree again every 2 seconds.

**Diagnostic procedure**

1. Check that the apps run - expected: the Keryx page shows `hdvisionsystems` with the apps.
2. Compare `--keryx-url` of the connector with the broker address the apps name in their logs - expected: the same address.
3. Browse again after about 2 seconds - expected: an app that started later shows up.

**Resolution**

- **If the apps are not running:** start them.
- **If the connector uses another address:** restart it with the same `--keryx-url` as the apps.
- **If an app started only recently:** browse again. There are no model change events: a client that cached its browse result must browse again.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the connector’s options and its log.

### Problem: `BadNodeIdUnknown` {#ts-opcua-bad-node-id}

**Symptoms**

A read, write or call over OPC UA answers `BadNodeIdUnknown`.

**Possible causes**

- The address, its case or the namespace index is wrong.
- The app is not running.
- The module is missing.

**Diagnostic procedure**

1. Look up the namespace index `n` of the URI `urn:hdvisionsystems:keryx` in the server’s `NamespaceArray` - expected: the index your program uses.
2. Check the NodeId - expected: `ns=<n>;s=<address>`, with the Data Layer address in lower case, for example `ns=<n>;s=hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code`.
3. Read `hdvisionsystems/<app>/system/found-modules` - expected: it lists the module.

**Resolution**

- **If the namespace index is wrong:** look it up by its URI after each connect. Do not write a fixed index into your program: another start can number it differently.
- **If the address is wrong:** correct case and spelling, see [Problem: A node is "not found"](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#node-not-found).
- **If the app is not running or the module is missing:** see [Problem: An app or a module is missing from the tree](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#app-missing).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the NodeId and the content of the server’s `NamespaceArray`.

### Problem: `BadTypeMismatch` on a write {#faq-opcua-type-mismatch}

**Symptoms**

A write over OPC UA answers `BadTypeMismatch`.

**Possible causes**

- The value’s type is not exactly the node’s type. The connector does not convert: a `Boolean` node takes a Boolean, not 0 or 1; a `UInt32` node takes UInt32, not Int32.

**Diagnostic procedure**

1. Look up the node’s type, for example on the Keryx page (select the node) - expected: the type your client sends, mapped as in [Reading, writing and types](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/opc-ua.html#types).

**Resolution**

- **If the type differs:** send exactly the node’s type, for example `Boolean` for flags and `UInt32` for `queue-size`.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the address of the node and the type your client sends.

### Problem: A subscription gets only one value, or misses results {#ts-opcua-subscription}

**Symptoms**

A monitored item reports only one value, or fewer notifications than the app pushes.

**Possible causes**

- The monitored item’s settings differ from the recommended ones: sampling interval not `0`, a queue size of 1 (only the newest push arrives), or a DataChange trigger other than `StatusValueTimestamp` (two identical results count as one).
- The node does not push: a value too large to be pushed never reports in event mode.
- The connector found at start that event mode does not work, and samples every item on a timer.

**Diagnostic procedure**

1. Compare the subscription with [Subscriptions](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/opc-ua.html#subscriptions) - expected: publishing interval 10 ms or more, sampling interval `0`, queue size 10 to 100, DataChange trigger `StatusValueTimestamp`, DiscardOldest `true`.
2. Read the connector’s log first - expected: no message that it uses sampled mode.

**Resolution**

- **If the settings differ:** set them as recommended. Use sampling interval `0` only on nodes that push.
- **If the node does not push:** use a positive sampling interval for it.
- **If the connector uses sampled mode:** contact support with its log.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the subscription settings and the connector’s log.

### Problem: Notifications stop after the connector or an app restarts {#ts-opcua-notifications-stop}

**Symptoms**

After the connector restarted, the client gets no notifications. After an app restarted, a monitored item does not report again, or reads answer `BadTimeout`, then `BadNoCommunication`.

**Possible causes**

- The connector restarted: the client’s subscriptions are gone.
- An app stopped or restarted. An app that stops keeps its nodes in the tree; reading them answers `BadTimeout`, then `BadNoCommunication`, until the app registers again. After the restart the camera is not connected and the Cam Driver’s stream is off.

**Diagnostic procedure**

1. Check whether the connector or an app restarted at the time the notifications stopped.
2. Read a node of the app - expected: a value, not `BadTimeout` or `BadNoCommunication`.

**Resolution**

- **If the connector restarted:** reconnect and create the subscriptions again.

- **If an app restarted:**

  a. Wait until the app has registered again.

  b. Run your start-up sequence again.

  c. If a monitored item does not report again, delete and create it.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#support-information) to support, together with the time of the restart and the connector’s log.

## Information for support {#support-information}

If the problem persists, contact [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com), +49 6221 6721905. For licences: [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com). Please send:

- the app and its version;
- the platform: Windows 11, Ubuntu 24.04, or ctrlX OS and its version;
- the date and time of the error;
- the log of the app; on ctrlX OS from the system log (Logbook of the ctrlX web interface, or `journalctl`);
- on a PC, the broker log from `C:\ProgramData\HD Vision Systems GmbH\LumiScan Keryx` (Windows) or `/tmp/lumiscan-keryx` (Ubuntu), and, if you use them, the logs of the OPC UA Connector and of LumiScan Keryx Utilities;
- the communication status: the Data Layer address the apps use, the content of `system/found-modules` and `system/status-text`, the module status (`control/status/code` and `text`, or a finder’s `status-code` and `status-text`), the result of a refused call, and over OPC UA the status code and the connector’s options;
- the configuration: the settings files of the app (on a PC in `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\<program>\etc\<settings folder>`, on ctrlX OS in the app’s folder of `/var/snap/rexroth-solutions/common/solutions/activeConfiguration`), or the content of `system/settings`, and on a PC `broker.json`.