---
title: "Reading Status, Quality & Errors"
description: "Understand entity status, data quality, the three error fields, and look up any error code"
source_url: https://ai-ops.com/docs/troubleshoot/reading-status-and-errors
---

# Reading Status, Quality & Errors

Every device, tag, model, binding, and scan group in Koios reports its health the same way: a **status**, and — when something goes wrong — three diagnostic error fields. This page is the shared reference for reading those signals and for looking up any error code you see anywhere in the product.

Start here, then follow the link for your specific error code to the article that owns its cause and fix.

## The Three Diagnostic Fields

When an entity hits a problem, Koios records three pieces of information:

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

Together they tell you what went wrong, why, and where to start investigating. The **error code** points you to the right troubleshooting article (see the [master lookup](#master-error-code-lookup) below); the **error message** and **error detail** give you the specifics for that instance.

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

## Status Legend

Every entity reports one of three stored statuses — **Running**, **Stopped**, or **Failed**. The rest of the states below are derived at display time by combining that status with the entity's enabled flag, its parent's state, and any advisory or test conditions.

| Status | Color | Meaning |
|--------|-------|---------|
| **Running** | Teal | Enabled entity operating normally. |
| **Stopped** | Gray | Disabled or cleanly stopped entity. |
| **Failed** | Red | The entity hit a failure; an error message is shown. |
| **Starting** | Gray | Transitional: enabled but not yet running (spinning up). Shown as an animated spinner. |
| **Stopping** | Gray | Transitional: disabled but still shutting down. Shown as an animated spinner. |
| **Warning** | Amber | Running, but with an advisory (e.g. overscanning). Behavior is normal; the amber strip flags attention. |
| **Testing** | Violet | A manual test-output override is active (test mode). Overrides the normal status display. |
| **Parent Disabled** | Gray | Stopped because the parent device or scan group is disabled. Not a transition — genuinely idle until the parent is enabled. |

> [!NOTE] Only three statuses are stored
> Running, Stopped, and Failed are the only persisted states. Starting, Stopping, Warning, Testing, and Parent Disabled are computed in the interface from those three plus context — you will not find them as distinct values in exports or the API.

## Data Quality Legend

Each tag also carries a **quality** value describing how much you can trust its most recent reading. Quality is a free-form string, so the exact text depends on the protocol, but it collapses to a few meanings:

| Quality | Color | Meaning |
|---------|-------|---------|
| **Good** | Teal | Successful read; the value is trustworthy. |
| **Bad** | Red | Read failed or the value is not trustworthy. Set on any read exception across every protocol. Drives tag error code `107 — Bad: Read Quality`. |
| **Uncertain** | Amber | OPC-UA only: the server returned an Uncertain-class status code. A value is present but the source flagged it as questionable. |
| _OPC-UA status code name_ | Gray | For OPC-UA reads, quality is the raw status code name (e.g. `Good`, `Uncertain`, `Bad_NodeIdUnknown`). Any `Bad_*` code, or an exception, collapses to `Bad`. |

> [!NOTE] Quality is not the same as an error code
> A `Bad` quality reading is what triggers the tag error `107 — Bad: Read Quality` and the binding error `12 — Binding Tag Bad Quality`. Those are error codes _caused by_ bad quality — not quality values themselves.

## Where Errors Surface

The same three fields appear in several places across the product:

- **Detail page hero + red strip**: a device, tag, model, or binding's Overview tab shows the status hero at the top. In a **Failed** state, a red error strip appears below it with the error message and detail. Click it to copy.
- **List tooltips**: in list tables, each row shows a colored status icon. Hovering a red icon displays that entity's error message as a tooltip.
- **Parameters / Live Data**: all three fields (error code, error message, error detail) are visible under the **Parameters** tab's **Live Data** section, alongside live values, timestamp, and scan progress.
- **Bindings tab (models)**: each binding card turns red and expands to show its own error message and detail inline — the most precise view of _which_ input or output failed.

## Auto-Clear Behavior

You never manually acknowledge or dismiss an error. Errors clear on their own: once the underlying issue is resolved, the next successful scan or inference cycle resets the error code to **None** and clears the message and detail.

An error code of **0 (None)** means the entity has no active error — you will see this on healthy entities and after a problem resolves.

## Stuck-Entity Checklist

If an entity stays failed and does not recover on its own, work through these five steps in order:

1. **Read the error message and detail.** They name the specific failure. Look up the error code in the [master lookup](#master-error-code-lookup) to find the article that covers its cause and fix.
2. **Review the logs at Debug level.** Open the entity's Logs tab and raise the log level for maximum detail. See [System Logs](https://ai-ops.com/docs/system/logs.md) for setting the Debug level and streaming logs.
3. **Verify the configuration.** Check the connection parameters (devices) or protocol settings (tags) on the Configuration tab.
4. **Use Test.** Run a one-time connection or read from the Configuration tab to reproduce the error in isolation, without enabling the entity.
5. **Toggle off and on.** Flip the **Enabled** switch off, then on, to force a fresh start.

## Master Error-Code Lookup

Every error code in Koios is listed below, grouped by the entity it belongs to. Each row links to the troubleshooting article that owns the **cause and fix** for that code. This page is the index — the detailed remediation lives in the linked article.

Error codes are non-contiguous by design (they band by failure stage), so gaps in the numbering are expected.

### Device Error Codes

| Code | Meaning | Where to go |
|------|---------|-------------|
| 0 | None — operating normally | — |
| 1 | Failed to Connect | [Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| 5 | Failed to Read from Device | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 6 | Failed to Write to Device | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 7 | Failed to Read Config from Database | [Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| 11 | Failed to Initialize | [Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| 12 | Failed to Write to Model History | [Stale Data](https://ai-ops.com/docs/troubleshoot/stale-data.md) |
| 13 | Failed to Write to Long Term History | [Stale Data](https://ai-ops.com/docs/troubleshoot/stale-data.md) |
| 14 | Failed to Update Heartbeat | [Services & Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| 15 | Failed to Cleanup | [Services & Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| 16 | Failed to Validate Tags | [Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| 17 | Failed to Write Executions | [Services & Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| 999 | Unlicensed | [Licensing](https://ai-ops.com/docs/troubleshoot/licensing.md) |

### Tag Error Codes

| Code | Meaning | Where to go |
|------|---------|-------------|
| 0 | None — value is good | — |
| 1 | Parent Device Failed | [Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| 2 | Generic Exception | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 100 | Bad: General | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 101 | Bad: Failed to Write | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 102 | Bad: Node Not Found | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 103 | Bad: Not a Number | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 104 | Bad: Configuration Error | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 105 | Bad: No Value | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 106 | Bad: Failed to Read | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 107 | Bad: Read Quality | [Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) |
| 108 | Mapping Error | [Expressions & Mapping](https://ai-ops.com/docs/troubleshoot/expressions-and-mapping.md) |
| 109 | No Active Device | [Connection](https://ai-ops.com/docs/troubleshoot/connection.md) |
| 110 | Bad: Expression | [Expressions & Mapping](https://ai-ops.com/docs/troubleshoot/expressions-and-mapping.md) |
| 200 | Failed to Historize | [Stale Data](https://ai-ops.com/docs/troubleshoot/stale-data.md) |
| 999 | Unlicensed | [Licensing](https://ai-ops.com/docs/troubleshoot/licensing.md) |

### Model Error Codes

| Code | Meaning | Where to go |
|------|---------|-------------|
| 0 | None — operating normally | — |
| 1 | No File Given | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 2 | No File Found | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 3 | Failed to Parse File | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 4 | Failed to Get Model Depth | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 5 | Failed to Get Bindings | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 6 | Bindings Invalid State | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 7 | Failed to Structure History | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 8 | Failed to Get Predictions | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 9 | Binding Prediction Index Missing | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 10 | Failed to Scale Predictions | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 11 | Failed to Write Predictions | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 12 | Thread Error | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 13 | Generic Exception | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 999 | Unlicensed | [Licensing](https://ai-ops.com/docs/troubleshoot/licensing.md) |

### Binding Error Codes

| Code | Meaning | Where to go |
|------|---------|-------------|
| 0 | None — operating normally | — |
| 1 | Not Enough Historical Depth | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 2 | Stale History Data | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 3 | No Range Given | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 4 | Invalid Range Given | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 5 | Value Out of Range | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 6 | Failed to Normalize | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 7 | Failed to Structure History | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 8 | Prediction Index Missing | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 9 | Failed to Scale Prediction | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 10 | Failed to Write Prediction | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 11 | Binding Tag Disabled | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 12 | Binding Tag Bad Quality | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 13 | Binding Tag Failed | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 14 | Binding Tag Not Assigned | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 15 | Binding Not in Dictionary | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 16 | Failed to Structure Input Data | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 17 | Upstream Model Failure | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 18 | General Model Failure | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 19 | Rate of Change Exceeded | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 20 | On-Demand Read Failed | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 21 | Invalid Calibration | [Models](https://ai-ops.com/docs/troubleshoot/models.md) |
| 999 | Unlicensed | [Licensing](https://ai-ops.com/docs/troubleshoot/licensing.md) |

### Scan Group Error Codes

| Code | Meaning | Where to go |
|------|---------|-------------|
| 0 | None — running normally | — |
| 1 | Overscan | [Services & Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| 2 | On-Demand Read Failed | [Services & Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| 3 | On-Demand Write Failed | [Services & Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |
| 99 | Generic Exception | [Services & Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) |

> [!NOTE] Scan groups have no license code
> Scan groups do not report `999 — Unlicensed`. Their catch-all is `99 — Generic Exception`.

## What's Next

- [Troubleshooting Koios](https://ai-ops.com/docs/troubleshoot/introduction.md) — the symptom router that points you to the right layer
- [Troubleshoot a Connection](https://ai-ops.com/docs/troubleshoot/connection.md) — device and tag connectivity, certificates, network, and the Test button
- [Bad, Missing, or Frozen Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md) — bad quality, no value, read/write, and configuration errors
- [Expression & Value-Mapping Errors](https://ai-ops.com/docs/troubleshoot/expressions-and-mapping.md) — calculated-field and mapping failures
- [A Model or Binding Isn't Running](https://ai-ops.com/docs/troubleshoot/models.md) — model and binding inference errors
- [Data Is Stale, Frozen, or Has Gaps](https://ai-ops.com/docs/troubleshoot/stale-data.md) — historization and trend gaps
- [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md) — services, heartbeats, scan groups, and resource alarms
- [Licensing Problems](https://ai-ops.com/docs/troubleshoot/licensing.md) — license state and the Unlicensed (999) code
- [System Logs](https://ai-ops.com/docs/system/logs.md) — set the Debug log level and stream logs