---
title: "Troubleshooting a Device"
description: "How to diagnose and resolve device errors in Koios"
source_url: https://ai-ops.com/docs/devices/troubleshooting
---

# Troubleshooting a Device

When a device encounters a problem during its scan cycle, Koios records three pieces of diagnostic information:

- **Error Code** — a category that identifies _what kind_ of failure occurred
- **Error Message** — a short description of the problem (e.g. "Failed to connect")
- **Error Detail** — additional context, typically the underlying exception or system message that caused the failure

Together, these three fields tell you what went wrong, why, and where to start investigating.

## Where Errors Appear

### Device Detail Page

On a device's **Overview** tab, the status hero banner at the top shows the current state. When a device is in a **Failed** state, a red error strip appears below the status showing the error message and error detail. You can click this strip to copy the full error text to your clipboard.

### Device List

In the device list table, each device shows a colored status icon. When a device has failed, hovering over the red icon displays the error message as a tooltip.

### Parameters Tab

All three error fields — error code, error message, and error detail — are also visible in the **Parameters** tab under the **Live Data** section, alongside other real-time values like heartbeat and scan progress.

> [!TIP] Copy errors quickly
> On the device detail page, click the error strip to copy both the error message and error detail to your clipboard. This is useful when sharing diagnostics or searching logs.

## Error Codes Reference

Each error code corresponds to a specific stage in the device's scan cycle. When Koios reports an error code, the accompanying error message and error detail provide the specifics.

### Connection Errors

| Code | Name | Description |
|------|------|-------------|
| 1 | **Failed to Connect** | Koios could not establish a connection to the device. Check that the device is powered on, reachable on the network, and that connection parameters (hostname, port, credentials) are correct. |

### Scan Cycle Errors

| Code | Name | Description |
|------|------|-------------|
| 5 | **Failed to Read from Device** | The connection was established, but Koios could not read tag values from the device. This can happen if the device becomes unreachable mid-scan, or if a tag references an invalid address or node. |
| 6 | **Failed to Write to Device** | Koios could not write output values back to the device. Check that output tags have valid addresses and that the device allows writes with the current credentials. |
| 16 | **Failed to Validate Tags** | Tag configuration could not be validated before scanning. This typically means one or more tags have invalid or missing protocol-specific settings (e.g. a Modbus tag without a register address). |

### Initialization Errors

| Code | Name | Description |
|------|------|-------------|
| 11 | **Failed to Initialize** | The device could not complete its startup sequence. This includes loading initial tag state from the cache and preparing for the first scan. |

### Data Storage Errors

| Code | Name | Description |
|------|------|-------------|
| 7 | **Failed to Read Config from Database** | Koios could not read the device's configuration from the database. This is rare and usually indicates a database connectivity issue. |
| 12 | **Failed to Write to Model History** | Tag values could not be written to the model history database (used by AI models for inference). The device itself is still scanning, but model predictions may be affected. |
| 13 | **Failed to Write to Long Term History** | Tag values could not be written to the time-series database. The device is still scanning and live values are available, but historical data will have a gap. |
| 17 | **Failed to Write Executions** | Execution metadata could not be written to the database. |

### Housekeeping Errors

| Code | Name | Description |
|------|------|-------------|
| 14 | **Failed to Update Heartbeat** | The heartbeat counter could not be toggled after a scan. The device is still scanning normally — this error affects only the heartbeat signal that external systems may monitor. |
| 15 | **Failed to Cleanup** | Post-scan cleanup (resetting error states, updating status counters) did not complete successfully. |

### License Errors

| Code | Name | Description |
|------|------|-------------|
| 999 | **Unlicensed** | The device cannot scan because the Koios license does not cover it. This happens when the number of enabled devices exceeds the license limit. Disable unused devices or upgrade your license. |

> [!NOTE] Error code 0 means no error
> An error code of **0** (None) means the device has no active error. You'll see this on healthy devices or after an error has been resolved.

## Testing a Connection

You can test a device's connection without enabling it or saving configuration changes. On a device's **Configuration** tab, each protocol section includes a **Test** button.

### How It Works

1. Open the device's **Configuration** tab
2. Fill in or edit the connection parameters (hostname, port, credentials, etc.)
3. Click **Test** — Koios attempts a one-time connection to the device using the current form values

The button shows the result:

| State | Meaning |
|-------|---------|
| **Test** | Ready to test (idle) |
| **Testing...** | Connection attempt in progress |
| **Success** (green check) | Koios connected successfully |
| **Failed** (red X) | Connection failed — an error message appears below the form |

> [!NOTE] Testing uses unsaved values
> The test uses whatever values are currently in the form, even if you haven't saved yet. This lets you try different connection settings before committing. The test does not modify the saved configuration.

### When to Test

- **During initial setup** — verify the connection before enabling the device for the first time
- **After changing connection parameters** — confirm the new settings work before saving
- **When troubleshooting** — confirm whether the device is reachable on the network

## How Errors Are Resolved

Errors clear automatically when the device completes a successful scan. You don't need to manually acknowledge or dismiss them — once the underlying issue is resolved (e.g. the device is back online, credentials are corrected, or a tag is fixed), the next successful scan resets the error code to **None** and clears the error message and detail.

If a device is stuck in a failed state:

1. Check the **error message** and **error detail** for specifics
2. Review the device's **logs** (on the Logs tab) for more context — set the log level to **Debug** for maximum detail
3. Verify the device's **connection parameters** on the Configuration tab
4. Use the **Test** button to verify the connection without enabling the device
5. Try toggling the device off and on with the **Enabled** switch