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

# Troubleshooting a Tag

When a tag encounters a problem during its device's 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 read tag")
- **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

### Tag Detail Page

On a tag's **Overview** tab, the status hero banner at the top shows the current state. When a tag 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.

If the tag also has an **info message** (a non-error status note), it appears as a separate blue strip below the error.

### Tag List

In the tag list table, each tag shows a colored status icon. When a tag 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 the tag's current value and timestamp.

> [!TIP] Copy errors quickly
> On the tag 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 tag's read/write cycle. When Koios reports an error code, the accompanying error message and error detail provide the specifics.

### Parent Device Errors

| Code | Name | Description |
|------|------|-------------|
| 1 | **Parent Failed** | The tag's parent device has failed, so the tag cannot be scanned. Check the device's own error for the root cause — once the device recovers, this tag error clears automatically. |

### General Errors

| Code | Name | Description |
|------|------|-------------|
| 2 | **Exception** | A general exception occurred during tag value read or write. The error detail will contain the specific exception message. This is a catch-all for unexpected failures that don't fit a more specific error code. |

### Read Errors

| Code | Name | Description |
|------|------|-------------|
| 105 | **No Value** | The protocol returned no value for this tag. This can happen if the data point doesn't exist on the device, the register is empty, or the device returned a null response. Check that the tag's protocol settings (node ID, register address, etc.) are correct. |
| 106 | **Read Failed** | Koios could not read this tag's value from the device. This is a general read failure — the error detail will contain the specific exception. Common causes include invalid addresses, permission issues, or the device disconnecting mid-scan. |
| 107 | **Read Quality Bad** | The value was read but the data source reported poor quality. For OPC-UA tags, this means the server returned a quality status other than "Good" (e.g. Bad, Uncertain). The value may be stale or unreliable. |

### Write Errors

| Code | Name | Description |
|------|------|-------------|
| 101 | **Write Failed** | Koios could not write an output value back to the device. Check that the tag address is valid for writing, that the device allows writes with the current credentials, and that the value is within the device's accepted range. |
| 102 | **Bad: Node Not Found** | The OPC-UA node referenced by this tag does not exist on the server. Verify the node ID on the tag's **Configuration** tab — the namespace index or identifier may have changed. Use the OPC-UA browser to re-select the correct node. |

### Value Errors

| Code | Name | Description |
|------|------|-------------|
| 103 | **Not a Number** | The tag received a value that cannot be converted to a number. This happens when the device returns text, a special character, or an unexpected data type where a numeric value was expected. |

### Configuration Errors

| Code | Name | Description |
|------|------|-------------|
| 100 | **General Error** | A general tag error occurred that doesn't fit a more specific category. Check the error detail for more context. |
| 104 | **Configuration Error** | The tag's protocol-specific settings are invalid or incomplete. This typically appears during device initialization — for example, a Modbus tag without a register address, an OPC-UA tag with a malformed node ID, or a BOSS tag with an invalid variable code. Review the tag's **Configuration** tab and correct the settings. |

### Expression Errors

| Code | Name | Description |
|------|------|-------------|
| 110 | **Expression Error** | A calculation tag's expression failed to evaluate. This can be caused by syntax errors in the formula, division by zero, referencing tags that don't exist, or circular dependencies between expression tags. Review the expression on the tag's **Configuration** tab. |

### Mapping Errors

| Code | Name | Description |
|------|------|-------------|
| 108 | **Mapping Error** | The tag's value mapping or transformation failed. This is set by the mapping service when it encounters an error processing this tag's mapped value. Check the tag's mapping configuration and ensure the mapped source is valid. |

### Redundancy Errors

| Code | Name | Description |
|------|------|-------------|
| 109 | **No Active Device** | This tag is configured for redundancy (reading from a device set), but no device in the set is currently active. Check that at least one device in the device set is enabled and running. |

### Data Storage Errors

| Code | Name | Description |
|------|------|-------------|
| 200 | **History Failure** | The tag's value could not be written to the time-series database. The tag is still being scanned and its live value is available, but historical data will have a gap for this period. |

### License Errors

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

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

## Common Scenarios

### Tag failed but device is running

If the device is running but an individual tag is in a failed state, the problem is specific to that tag — not the connection. Common causes:

- **Wrong address** — the tag's node ID, register address, or query points to something that doesn't exist on the device. Use the **Browse** button on the Configuration tab to re-select the correct data point.
- **Data type mismatch** — the configured data type doesn't match what the device is actually returning. Try a different data type in the protocol settings.
- **Permission denied** — the device credentials don't have permission to read or write this specific data point.

### All tags on a device failed

If every tag on a device shows **Parent Failed** (error code 1), the problem is at the device level. Navigate to the device's detail page and troubleshoot the device error first — see [Troubleshooting a Device](https://ai-ops.com/docs/devices/troubleshooting.md).

### Tag shows "Device is stopped"

If a tag is enabled but its parent device is stopped, you'll see an info banner on the tag's overview: **"Device is stopped — Tag will not be updated until device is enabled and running."** This isn't an error — enable and start the parent device to begin scanning.

### Tag is not historizing properly

If a tag's live value is updating but Trends show flat lines or far fewer recorded points than expected, the cause is almost always a mismatch between the tag's **Range Min / Max** and the compression settings.

Koios uses **Swinging Door Trending (SDT)** to compress historical data. SDT calculates a tolerance band as a percentage of the tag's configured range — not the actual value. If the range is left at the default **0–100** but the tag only moves between **0 and 1**, the tolerance band is wider than the entire signal and almost nothing gets recorded.

**How to fix it:**

1. Set the tag's **Range Min** and **Range Max** to match the actual expected value range (e.g. **0–1**, not 0–100)
2. Review the global **Compression Deviation** in [System > Retention > History Compression](https://ai-ops.com/docs/system/retention.md#history-compression) — 1–2% is a good starting point
3. If only this tag needs special treatment, enable **Override global compression settings** on the tag's Configuration tab and set a tighter deviation or disable compression for this tag alone
4. To disable compression globally, turn off the **Compression Enabled** toggle on the Retention page

> [!WARNING] Check the range on every tag
> The default range of 0–100 causes silent data loss for tags with narrow value bands (0–1, 4–20 mA, 0.0–5.0). This is the most common cause of missing historical data. See [Tag Range and Compression](https://ai-ops.com/docs/system/retention.md#tag-range-and-compression) for a full explanation of how SDT interacts with the tag range.

## Testing a Tag

You can test whether Koios can read a value from a tag without enabling it. On a tag's **Configuration** tab, each protocol section includes a **Test** button.

### How It Works

1. Open the tag's **Configuration** tab
2. Ensure the protocol settings are saved (node ID, register address, expression, etc.)
3. Click **Test** — Koios performs a one-time read from the device for this tag

The button shows the result:

| State | Meaning |
|-------|---------|
| **Test** | Ready to test (idle) |
| **Testing...** | Read attempt in progress |
| **Success** (green check) | Koios read a value — the result message shows the value returned |
| **Failed** (red X) | Read failed — an error message appears below the form |

> [!NOTE] Testing uses saved configuration
> Unlike device connection tests, tag tests use the tag's **saved** configuration. Make sure you save any protocol setting changes before testing.

> [!TIP] The device must be reachable
> The tag test connects to the device in real time. The device must be powered on and reachable on the network, but it does not need to be enabled in Koios. The test uses a one-time connection separate from the scan cycle.

### When to Test

- **After creating a tag** — verify the protocol settings are correct before enabling
- **After using a device browser** — confirm the auto-populated settings read the expected value
- **When troubleshooting** — isolate whether the problem is with the tag's configuration or the device connection

## How Errors Are Resolved

Tag errors clear automatically when the tag is successfully read or written on the next scan. You don't need to manually acknowledge or dismiss them — once the underlying issue is resolved (e.g. the address is corrected, the device recovers, or the expression is fixed), the next successful scan resets the error code to **None** and clears the error message and detail.

If a tag is stuck in a failed state:

1. Check the **error message** and **error detail** for specifics
2. Review the device's **logs** — set the device's log level to **Debug** for maximum detail about tag-level operations
3. Verify the tag's **protocol settings** on the Configuration tab
4. Use the **Test** button to attempt a single read and see if the error reproduces
5. Try toggling the tag off and on with the **Enabled** switch