---
title: "Troubleshooting"
description: "Step-by-step help for LumiScan Cam Driver problems - cameras that do not appear or connect, refused methods, status codes, image capture and storage, the image stream and licences."
product: "LumiScan Cam Driver"
component: "lumiscan-cam-driver"
version: "2.2.1"
display_version: "2.2.1.10"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html"
---

# Troubleshooting – LumiScan Cam Driver

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}

The Cam Driver uses a two-level configuration:

- The **app configuration** (`lumiscan-cam-driver.json`) defines which camera modules are loaded.
- Each **camera configuration** (for example `camera_example.json`) represents one camera.

If a camera configuration is missing, invalid, or not referenced correctly, the camera is not loaded and does not appear in the Data Layer.

Configurations are available under:

| Platform | Location |
| --- | --- |
| ctrlX OS | `Manage App Data > active > lumiscan-cam-driver` |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-cam-driver`, or without `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cam-driver\etc\lumiscan-cam-driver` |

On both platforms, `/hdvisionsystems/lumiscan-cam-driver/system/settings` shows the files as the Cam Driver read them at start. A module file that could not be read appears there with an `"$error"` that says why. The Cam Driver reads its files only at start: restart the application after you change a file. See [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#what-the-node-shows).

### Status of a camera module {#general-status}

Each camera module reports the outcome of its last operation on `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/code` (a number) and `.../control/status/text` (its name). The meaning of each value is listed in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#status-code-values).

- A failed `capture` through the handshake ends at status `3` (`waitingForClient`), not at its own error code. `control/capture/execute` keeps the capture’s own code. See [When a Functionality Runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html#when-a-functionality-runs).
- A failed `capture`, `reset`, `save` or `load` is latched: its status stays until a `reset` succeeds. Any other error stays on `control/status/code` for about 100 ms only.
- Check whether a camera is connected with `<camera name>/device-info/is-connected`, not with the status.

### Logs {#general-logs}

If an issue persists, check the log for additional error information:

- **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 the Cam Driver in its console.

`logLevel` in the `system` section of `lumiscan-cam-driver.json` sets the log level: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` or `OFF`. See [Application Settings Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html).

A program that calls an `execute` method again and again while it is refused, for example `capture/execute` while the camera is busy, would write one log line per call. For each method and result, the application logs the first refusal, then at most one line every ten seconds, which says how many refusals were not logged one by one, for example "(+250 like it since the last one logged)". The `execute` result itself is still returned for every call.

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

For problems that concern the Data Layer itself - the broker of LumiScan Keryx, nodes that are not found, method results - see [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html) of LumiScan Keryx.

## Configuration and start {#configuration-and-start}

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

**Symptoms**

There is no node `/hdvisionsystems/lumiscan-cam-driver/<module>` for a camera that you configured.

**Possible causes**

- The camera configuration is missing, invalid, or not referenced correctly in `lumiscan-cam-driver.json`. The camera module is then not loaded.
- The module’s `id` contains characters other than lower-case letters, digits, `-` and `_`.
- The file was changed, but the application was not restarted. The Cam Driver reads its files only at start.
- The whole application is missing from the Data Layer, for example because the licence is missing (ctrlX OS) or the application uses another broker (PC).

**Diagnostic procedure**

1. Read `/hdvisionsystems/lumiscan-cam-driver/system/settings` - expected: the module’s content in the `modules` list. A module file that could not be read appears as `{"$file": ..., "$error": ...}`; `"$error"` says why.
2. Check that the camera configuration file is entered in the list of camera configuration files in `lumiscan-cam-driver.json` - expected: its file name is listed.
3. Check the `id` in the camera configuration file - expected: only lower-case letters, digits, `-` and `_`, and unique across all camera settings.
4. Read the log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#general-logs)) - expected: no error for the module. For an invalid `id`, the log says which id to write instead.
5. If no node `/hdvisionsystems/lumiscan-cam-driver` exists at all, the application itself is not running.

**Resolution**

- **If the camera configuration is missing, invalid or not referenced:** correct the app configuration and the camera configuration so that they reference each other correctly.
  1. Correct the files, or change them on the Data Layer through `system/settings`.
  2. Restart the application, for example with `hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute`.
  3. Check that `/hdvisionsystems/lumiscan-cam-driver/<module>` exists.
- **If the `id` has invalid characters:** write the id that the log names (for example `Camera1` → `camera1`), then restart the application. See [Camera Example File Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html).
- **If the application is missing from the Data Layer:** on ctrlX OS, see [Problem: "No valid license found, please purchase one. If you do have one, please try to restart ctrlX"](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-missing-license). For a PC and for other Data Layer causes, see [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-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of `system/settings` and the log lines from the start of the application.

### Problem: Modules answer no request, and the status is -5 "restartRequired" {#faq-restart-required}

**Symptoms**

- `control/status/code` is `-5` (`restartRequired`) on every module.
- `hdvisionsystems/lumiscan-cam-driver/system/restart-required` is `true`.
- Every `execute` method of a module answers `DL_RESOURCE_UNAVAILABLE` (`ResourceUnavailable` on LumiScan Keryx), and the `ready` signals are `false`.
- A running image stream stops.

**Possible causes**

- The settings were changed on the Data Layer (`system/settings`, `activate-module`, `deactivate-module`). Until the next start, the application runs with settings that are no longer those of its files.
- A changed file could not be saved: the write answered `DL_CREATION_FAILED`. Files changed before it stay changed, so the application requires a restart all the same.

**Diagnostic procedure**

1. Read `hdvisionsystems/lumiscan-cam-driver/system/restart-required` - expected: `true`.
2. Read `hdvisionsystems/lumiscan-cam-driver/system/status-text` - it says which files changed.
3. Read the log - the message is at error level.

**Resolution**

- **If the settings were changed on the Data Layer:**
  1. Call `hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute`. A `reset` does not help.
  2. Wait until `system/restart-required` can be read again. On ctrlX OS, the application ends, and ctrlX OS starts it again after about five seconds.
- **If a write answered `DL_CREATION_FAILED`:** correct the files, then restart the application as above.

See [Restart required](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#restart-required).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of `system/status-text` and `system/settings`.

### Problem: "No valid license found, please purchase one. If you do have one, please try to restart ctrlX" {#faq-missing-license}

**Symptoms**

- `control/status/code` is `-4` (`missingLicense`) with the text `No valid license found, please
  purchase one. If you do have one, please try to restart ctrlX`.
- On ctrlX OS, the application stops shortly after starting.
- From v2.2.0, the application logs a warning and shuts down when a licence is lost.

**Possible causes**

- No valid licence is installed, or not enough for the configured cameras: you need one licence per connected camera.
- A version 1 key is installed. From v2.0.0, the Cam Driver needs the licence `SWL-W-XCx-CAMDRIVERxHDVSx-V2NN`.
- Up to and including v2.1.0: the licences were installed separately. Only the first Cam Driver V2 entry is read.

**Diagnostic procedure**

1. Read the ctrlX OS system log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#general-logs)) - it names the reason, the missing licence.
2. Open the **Licenses** page of ctrlX OS - expected: Cam Driver V2 licences for all connected cameras. Up to and including v2.1.0: one Cam Driver V2 entry that covers all cameras.
3. Compare the number of licences with the number of connected cameras - expected: one licence per camera.

**Resolution**

- **If no licence or not enough licences are installed:** install one licence `SWL-W-XCx-CAMDRIVERxHDVSx-V2NN` per connected camera. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html#licence).
- **If a version 1 key is installed:** replace it with a V2 licence. Version 1 keys do not work from v2.0.0.
- **If the licences were installed separately (v2.1.0 and earlier):** install all licences together, so that the **Licenses** page shows one Cam Driver V2 entry covering all cameras, or update to v2.2.0, which also supports separately installed licences.
- For other purchase routes and licence problems, see the [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html) and [Licensing troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/troubleshooting.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the log lines that name the missing licence. For licences, contact [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

## Camera connection {#camera-connection}

### Problem: A physically connected camera is not detected {#faq-camera-not-detected}

**Symptoms**

The camera is missing from the lists under `/hdvisionsystems/lumiscan-cam-driver/system`: `found-camera-ip-addresses`, `found-camera-mac-addresses`, `found-camera-modules` and `found-camera-serials`.

**Possible causes**

- The camera is not connected to the ctrlX CORE or the PC, or (ctrlX OS) not to a supported ctrlX port.
- The camera is not powered, either externally or via PoE.
- The IP addresses of the ctrlX CORE or the PC and of the camera are not configured correctly: the camera IP must be in the same local network.
- Duplicate IP addresses exist in the network.

**Diagnostic procedure**

1. Read `found-camera-serials`, `found-camera-ip-addresses`, `found-camera-mac-addresses` and `found-camera-modules` under `/hdvisionsystems/lumiscan-cam-driver/system` - expected: the camera is detected, its IP address is correct, and the serial number matches the expected device.
2. Check the cable - expected: the camera is connected to the ctrlX CORE or the PC; on ctrlX OS, to a supported ctrlX port.
3. Check the power supply - expected: the camera is powered, externally or via PoE.
4. Compare the IP address and subnet of the camera with those of the ctrlX CORE or the PC - expected: the camera is in the same local network.
5. Check the network for duplicate IP addresses - expected: each device has a unique IP address.

**Resolution**

- **If the camera is not connected or not powered:** connect it to the ctrlX CORE or the PC (on ctrlX OS, to a supported ctrlX port) and power it. For a ctrlX CORE X3, see [Hardware Setup for ctrlX X3](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#overview).
- **If the IP address is wrong:** set it with the force-IP function under `hdvisionsystems/lumiscan-cam-driver/system/force-ip/`. It also works when the subnet of the camera does not match the ctrlX CORE or the PC, as long as the camera is reachable over the same network connection. See [Setup Camera IP Address](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/setup-camera-ip-address.html).
  1. Read the camera’s MAC address from `system/found-camera-mac-addresses` (same position in the list as its serial in `system/found-camera-serials`).
  2. Set `gateway`, `ip`, `subnet` and the camera’s MAC address.
  3. Wait until `ready` is `true`, set `request` to `true`, then back to `false`.
  4. When `ready` is `true` again, check that `system/found-camera-ip-addresses` shows the new address. If it does not, use the camera supplier’s program to set the IP.
- **If duplicate IP addresses exist:** give each device a unique IP address. On a ctrlX CORE X3, `192.168.1.1` is used by XF10: do not assign it to the camera or the computer.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of the four `found-camera-…` lists and the network topology (switch or direct connection).

### Problem: The camera does not connect (status -10000 "failedToConnectToCamera") {#faq-failed-to-connect-to-camera}

**Symptoms**

- After the `connect-camera` handshake, `/hdvisionsystems/lumiscan-cam-driver/<module>/device-info/is-connected` stays `false`.
- `control/status/code` shows `-10000` (`failedToConnectToCamera`) for about 100 ms only, then `0` again, with the camera still not connected.

**Possible causes**

- The camera is not detected, see [Problem: A physically connected camera is not detected](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-camera-not-detected).
- The camera was unplugged and plugged back in.
- The Ethernet configuration, such as buffer sizes and jumbo frames, does not match the camera specifications.
- A PC on the same switch is accessing the camera at the same time. Parallel access can interfere with camera communication.
- More than one process writes `connect-camera/request`, so the application misses the request.

**Diagnostic procedure**

1. Read `<module>/device-info/is-connected` - expected: `true` after `connect-camera`. Do not judge the connection by `control/status/code`.
2. Check that the camera appears under `/hdvisionsystems/lumiscan-cam-driver/system` - expected: its serial is in `found-camera-serials`.
3. Before the request, read `<module>/control/connect-camera/ready` - expected: `true`. If it is `false`, the precondition is not met or no camera is found: check that the camera IP is in the same local network as the ctrlX CORE or the PC.
4. After setting `connect-camera/request` to `true`, read `connect-camera/ready` - expected: `false` (the application has seen the request).
5. Check whether a PC on the same switch accesses the camera - expected: it does not.

**Resolution**

- **If the camera is not detected:** follow [Problem: A physically connected camera is not detected](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-camera-not-detected).
- **If the camera was unplugged and plugged back in (from v2.1.0):** run the `reset` handshake, which reports `failedToConnectToCamera` until it succeeds, then run `connect-camera`. `connect-camera` has no `execute` method: use the handshake on `/hdvisionsystems/lumiscan-cam-driver/<module>/control/connect-camera/request`. See [Connection Steps](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#connection-steps).
- **If the connection still fails:**
  1. Power-cycle the camera by disconnecting it for approximately 30 seconds and reconnecting it.
  2. Verify that the camera appears in the Data Layer.
  3. Check the Ethernet configuration, such as buffer sizes and jumbo frames, according to the camera specifications.
- **If a PC accesses the camera at the same time:** stop that access.
- **If the application does not see the request:** make sure that only one process accesses `connect-camera/request` at a time, and that you use the same Data Layer version as the camera application.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the camera serial number, the value of `device-info/is-connected` and the log lines of the connection attempt.

## Image capture and saving {#image-capture-and-saving}

### Problem: Image capture fails or is unreliable (status -10004 "couldNotCaptureImage") {#faq-could-not-capture-image}

**Symptoms**

- `capture/execute` leaves `control/status/code` at `-10004` (`couldNotCaptureImage`).
- Through the handshake, a failed capture ends at status `3`, and `capture/ready` stays `false` until a `reset` succeeds.
- Images cannot be triggered reliably.

**Possible causes**

- The camera is disconnected.
- Communication fails because of poor connection quality.
- The MTU size of the Ethernet port (ctrlX OS) or of the network adapter (PC) is too small.
- A network component does not support the required data throughput.

**Diagnostic procedure**

1. Read `<module>/device-info/is-connected` - expected: `true`.
2. Check the cable - expected: a "Foil Shielded Twisted Pair" cable.
3. Check the MTU size - expected: 8000 or 9000.
   - ctrlX OS: **Settings** > **Network Interfaces** > the port in use > **Advanced Settings**.
   - PC: the MTU size (jumbo frames) of the network adapter the camera is connected to.
4. As a quick test, reduce the ROI - if image acquisition becomes more stable, the issue is likely related to network bandwidth.

**Resolution**

- **If the camera is disconnected:** reconnect it. A failed capture is latched: run `reset` and then `connect-camera` with the handshake.
- **If the connection quality is poor:** use a "Foil Shielded Twisted Pair" cable.
- **If the MTU size is too small:** set it to 8000 or 9000. On ctrlX OS, if the port cannot change the MTU size, use an Ethernet port that supports large MTU sizes. See [MTU Size Change](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#mtu-size-change).
- **If the network bandwidth is insufficient:** make sure all network components support the required data throughput. On a ctrlX CORE X3, test different packet delay values until image acquisition is stable, see [Complete the Camera Setup](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#complete-camera-setup). Camera parameters can be adjusted using the manufacturer’s software, through the camera’s feature nodes under `/hdvisionsystems/lumiscan-cam-driver/<module>/features`, or in a feature file listed in the module’s `cameras[].featureFiles`. See [GenICam features](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#genicam-features).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of `control/status/code` and `control/status/text`, the MTU size and the network topology.

### Problem: A write to execute answers "DL_TOO_MANY_OPERATIONS" or "TooManyOperations" {#faq-dl-too-many-operations}

**Symptoms**

A write to `<camera name>/control/<operation>/execute` answers `DL_TOO_MANY_OPERATIONS` (ctrlX Data Layer) or `TooManyOperations` (LumiScan Keryx).

**Possible causes**

- The camera is busy with another operation right now.
- The image stream is starting or stopping. After the stream stops, the camera is connected again; until then, `capture/execute` answers `DL_TOO_MANY_OPERATIONS`.

**Diagnostic procedure**

1. Read `control/status/code` - `2` (`running`): another operation runs.
2. Read `control/publish/output/stream/active` and `control/capture/ready` - after the stream stops, `capture/ready` turns `true` once the camera is connected again.

**Resolution**

- **If the camera is busy:** retry. A rejected write is never queued; the same write succeeds once the running operation has finished.
- **If the stream is starting or stopping:** wait until `capture/ready` is `true`. This takes about two seconds on the camera we tested.

`DL_RESOURCE_UNAVAILABLE` (`ResourceUnavailable`) is a different result: the application is shutting down - retrying does not help - or a restart is required, see [Problem: Modules answer no request, and the status is -5 "restartRequired"](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-restart-required). See [Calling execute](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#calling-execute).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the operation you call and the result it answers.

### Problem: A write to execute answers "DL_INVALID_OPERATION_MODE", or capture keeps being refused {#faq-dl-invalid-operation-mode}

**Symptoms**

- A write to `<camera name>/control/<operation>/execute` answers `DL_INVALID_OPERATION_MODE` (ctrlX Data Layer) or `InvalidOperationMode` (LumiScan Keryx). This applies to v2.2.0 and later; earlier versions reported this case as `DL_TOO_MANY_OPERATIONS`.
- `capture/execute` is refused again and again, also after the camera captured once.

**Possible causes**

The operation’s `ready` signal is `false`, so the camera is not in a state where the operation can run:

- `capture`: the camera is not connected, a capture fault is latched (after a failed capture), or the image stream runs.
- `save`: no image is available yet.
- `load`, `remove`: `<camera name>/output/image-files` is empty.
- `trigger`: the camera is not connected.

**Diagnostic procedure**

1. Read `<operation>/ready` - `false` names the missing precondition.
2. Read `control/status/code` and `control/status/text` - the status text still carries the message from the fault that caused it.
3. Read `<camera name>/device-info/is-connected` - expected: `true`.
4. Read `control/publish/output/stream/active` - `true`: the image stream runs.
5. For `load` and `remove`, read `<camera name>/output/image-files` - expected: not empty.

**Resolution**

Do not retry blindly; establish the precondition first:

- **If the camera is not connected, or a capture fault is latched:** run `reset` and then `connect-camera` with the handshake (`reset` hands back a disconnected camera). Both have no `execute` method, so a program that uses `execute` only must connect, and recover from a latched fault, through the handshake.
- **If the image stream runs:** stop it and wait until `capture/ready` is `true`, see [Problem: Capture is refused while the image stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-capture-refused-streaming).
- **If no image is available for `save`:** capture or load an image first.
- **If `output/image-files` is empty:** run `list-images` or save an image first.

See [When is an operation ready](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#when-is-an-operation-ready).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the values of `<operation>/ready`, `control/status/code` and `control/status/text`.

### Problem: Images are not saved (status -10006 "saveImageFailed" or -10005 "noImageTaken") {#faq-save-image-failed}

**Symptoms**

- `control/status/code` is `-10006` (`saveImageFailed`) or `-10005` (`noImageTaken`).
- **Save** does nothing, or there is no image in the storage folder.

**Possible causes**

- `noImageTaken`: no image has been captured yet.
- `saveImageFailed`: the storage cannot be written - `ip`, `username` or `password` in the storage settings are wrong, the IP is not reachable from the ctrlX CORE or the PC, or the shared folder has not enough free space.
- Storage is not configured, or configured incorrectly: without a `storage` block in the `system` section of `lumiscan-cam-driver.json`, **Save** does nothing.
- (ctrlX OS) The USB storage device or SD card is not mounted, or does not use FAT32 or EXT4.

**Diagnostic procedure**

1. Read `output/package-identifier` - if it is zero, no image has been captured, and `save/ready` is `false`.
2. Check the `storage` block in the `system` section of `lumiscan-cam-driver.json` - expected: a `type` (`Internal` or `Samba`) and its parameters. See [Storage settings](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html#storage-settings).
3. For `Samba`: check that `ip`, `username` and `password` are correct, that the IP is reachable from the ctrlX CORE or the PC, and that you can access the folder with the configured user account - expected: access works and the folder has free space.
4. For a USB storage device or SD card (ctrlX OS): check under **Settings** > **Storage Devices** that it is mounted - expected: its path (for example `/media/sdb1`) is the beginning of `rootPath`.
5. Read the log - it shows incorrect settings information.

**Resolution**

- **If no image has been captured (`noImageTaken`):** capture an image before saving.
- **If the storage cannot be written (`saveImageFailed`):** correct `ip`, `username` and `password`, make the IP reachable, or free space in the shared folder.
- **If storage is not configured or configured incorrectly:**
  1. Add or correct the `storage` block, see [Saving Image Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#saving-image-files).
  2. Restart the application.
  3. Call **Connect Camera**, **Capture** and **Save**, and check that an image is in the storage folder.
- **If the USB storage device or SD card is not mounted (ctrlX OS):** mount it under **Settings** > **Storage Devices** with **For data exchange**, and start `rootPath` with the path shown there.

A failed `save` is latched until a `reset` succeeds; a `save` before anything was captured (`-10005`) is not.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the `storage` block (the password is shown as `"*"` on `system/settings`) and the log lines of the failed save.

### Problem: Images do not match expectations {#ts-images-not-as-expected}

**Symptoms**

The captured images do not look as you expect from the camera settings.

**Possible causes**

- The camera settings are not saved or not applied correctly.
- A value was written to a feature node under `features`. Such a value is lost when the camera is connected again.
- The exposure time on `input/exposure-time` and the inter-packet delay are not applied while the image stream runs.

**Diagnostic procedure**

1. Save an image with `/hdvisionsystems/lumiscan-cam-driver/<module>/control/save/execute`, or the `save` handshake (`control/save/request`), and look at it - expected: it matches the settings.
2. Check where the camera features are set - expected: in a feature file listed in the module’s `cameras[].featureFiles`, which is applied each time the camera is connected.
3. Read `control/publish/output/stream/active` - `true`: the stream runs, and the exposure time is not applied.

**Resolution**

- **If the settings are not saved or not applied:** if the camera supports it, export the camera configuration, for example in GenICam format, and import it into LumiScan to keep the settings consistent.
- **If a value written to a feature node was lost:** put the feature into a feature file listed in the module’s `cameras[].featureFiles`. See [GenICam features](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#genicam-features).
- **If the image stream runs:** stop the stream, change the camera features, then start the stream again.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with a saved image, the camera configuration and the feature files.

## Image stream (experimental) {#image-stream}

### Problem: Capture is refused while the image stream runs {#faq-capture-refused-streaming}

**Symptoms**

- `control/capture/execute` answers `DL_INVALID_OPERATION_MODE` while the stream runs, and `DL_TOO_MANY_OPERATIONS` while the stream is starting or stopping.
- A capture request through the handshake ends with status `-3` (`invalidInput`) and the text `capture refused: the image stream (experimental) is active`.
- `control/capture/ready` is `false`.

**Possible causes**

- The experimental image stream runs. The stream and `capture` use the camera in different ways, so they never run at the same time.
- The stream has just stopped, and the camera is being connected again.

**Diagnostic procedure**

1. Read `control/publish/output/stream/active` - `true`: the stream runs.
2. After stopping the stream, read `control/capture/ready` - expected: `true` after about two seconds.

**Resolution**

- **If you need a capture:** stop the stream. No `reset` is needed: the refusal latches no fault.
  1. Write `false` to `control/publish/input/enable`.
  2. Call `control/publish/execute`.
  3. Wait until `control/capture/ready` is `true` again. That takes about two seconds on the camera we tested, because the camera is connected again after the stream.
- **If you need single images while streaming:** take them from `control/publish/output/stream/frame` instead of stopping the stream, or apply `keep-latest-output` and read `output/image` when `output/package-identifier` changes.

See [Capture while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#capture-while-streaming).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the values of `control/publish/output/stream/active` and `control/capture/ready`.

### Problem: The image stream delivers no images, or fewer than expected {#ts-stream-missing-images}

**Symptoms**

Your program receives no images on `control/publish/output/stream/frame`, or fewer than expected. A dropped image shows as a gap in the frame numbers (`sequence`).

**Possible causes**

- The stream does not run: the inputs were written, but `control/publish/execute` was not called; the stream could not start; or the Cam Driver was restarted - after a start, the stream is off.
- `frames` stays at `0`: the Cam Driver does not trigger the camera by itself.
- `frames` grows more slowly than the number of triggers you sent: the camera ignores triggers that come faster than it can take images.
- `lost-frames` or `incomplete-frames` grow: images were lost on the network.
- `published-frames` matches `frames`, but your program receives fewer: your subscriber falls far behind, and the Data Layer drops images.

**Diagnostic procedure**

1. Read `control/publish/output/stream/active` - expected: `true`.
2. Compare the counters under `/hdvisionsystems/lumiscan-cam-driver/<module>/control/publish/output/stream/statistics`: `frames`, `lost-frames`, `incomplete-frames` and `published-frames` - expected: `frames` grows with each trigger, `lost-frames` and `incomplete-frames` stay at `0`, and `published-frames` matches `frames`.
3. Compare the `sequence` numbers your program receives - expected: no gaps.

**Resolution**

- **If the stream does not run:** connect the camera, set `control/publish/input/enable` to `true` and call `control/publish/execute`. Do this after every start of the Cam Driver. If `control/publish/output/stream/active` stays `false`, the reason is in the log; the start is not retried until `control/publish/execute` is called again. See [Running a stream](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#running-a-stream).
- **If `frames` stays at `0`:** trigger the camera by hardware or with `control/trigger/execute`, or set its trigger mode off. See [Triggering the camera](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#triggering).
- **If `frames` grows more slowly than the triggers:** trigger less often, shorten the exposure, or set the camera’s `TriggerOverlap` to an overlap it supports, such as `PreviousFrame`, in a feature file. See [For the highest frame rate: TriggerOverlap](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#trigger-overlap).
- **If `lost-frames` or `incomplete-frames` grow:** check the network as described in [Problem: Image capture fails or is unreliable (status -10004 "couldNotCaptureImage")](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-could-not-capture-image).
- **If your program receives fewer images than `published-frames`:** make sure your subscriber handles each image quickly.

See also [A stream delivers nothing](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#stream-nothing).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the values of the counters under `control/publish/output/stream/statistics` and how the camera is triggered.

## 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 Cam Driver.
- 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 the Cam Driver.
- The date and time when the error occurred.
- The Data Layer status of the affected module: `control/status/code`, `control/status/text`, `device-info/is-connected`, and the result that an `execute` call answered.
- The camera: manufacturer, model and serial number (`system/found-camera-serials`).
- The configuration: `lumiscan-cam-driver.json`, the camera configuration files and feature files, or the content of `hdvisionsystems/lumiscan-cam-driver/system/settings`, which shows every password as `"*"`.