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 below); the error message and error detail give you the specifics for that instance.

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.

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`.

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:

Read the error message and detail. They name the specific failure. Look up the error code in the master lookup to find the article that covers its cause and fix.
Review the logs at Debug level. Open the entity's Logs tab and raise the log level for maximum detail. See System Logs for setting the Debug level and streaming logs.
Verify the configuration. Check the connection parameters (devices) or protocol settings (tags) on the Configuration tab.
Use Test. Run a one-time connection or read from the Configuration tab to reproduce the error in isolation, without enabling the entity.
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
5	Failed to Read from Device	Tag Values
6	Failed to Write to Device	Tag Values
7	Failed to Read Config from Database	Connection
11	Failed to Initialize	Connection
12	Failed to Write to Model History	Stale Data
13	Failed to Write to Long Term History	Stale Data
14	Failed to Update Heartbeat	Services & Alarms
15	Failed to Cleanup	Services & Alarms
16	Failed to Validate Tags	Connection
17	Failed to Write Executions	Services & Alarms
999	Unlicensed	Licensing

Tag Error Codes

Code	Meaning	Where to go
0	None — value is good	—
1	Parent Device Failed	Connection
2	Generic Exception	Tag Values
100	Bad: General	Tag Values
101	Bad: Failed to Write	Tag Values
102	Bad: Node Not Found	Tag Values
103	Bad: Not a Number	Tag Values
104	Bad: Configuration Error	Tag Values
105	Bad: No Value	Tag Values
106	Bad: Failed to Read	Tag Values
107	Bad: Read Quality	Tag Values
108	Mapping Error	Expressions & Mapping
109	No Active Device	Connection
110	Bad: Expression	Expressions & Mapping
200	Failed to Historize	Stale Data
999	Unlicensed	Licensing

Model Error Codes

Code	Meaning	Where to go
0	None — operating normally	—
1	No File Given	Models
2	No File Found	Models
3	Failed to Parse File	Models
4	Failed to Get Model Depth	Models
5	Failed to Get Bindings	Models
6	Bindings Invalid State	Models
7	Failed to Structure History	Models
8	Failed to Get Predictions	Models
9	Binding Prediction Index Missing	Models
10	Failed to Scale Predictions	Models
11	Failed to Write Predictions	Models
12	Thread Error	Models
13	Generic Exception	Models
999	Unlicensed	Licensing

Binding Error Codes

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

Scan Group Error Codes

Code	Meaning	Where to go
0	None — running normally	—
1	Overscan	Services & Alarms
2	On-Demand Read Failed	Services & Alarms
3	On-Demand Write Failed	Services & Alarms
99	Generic Exception	Services & Alarms

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 — the symptom router that points you to the right layer
Troubleshoot a Connection — device and tag connectivity, certificates, network, and the Test button
Bad, Missing, or Frozen Tag Values — bad quality, no value, read/write, and configuration errors
Expression & Value-Mapping Errors — calculated-field and mapping failures
A Model or Binding Isn't Running — model and binding inference errors
Data Is Stale, Frozen, or Has Gaps — historization and trend gaps
Service Health & Resource Alarms — services, heartbeats, scan groups, and resource alarms
Licensing Problems — license state and the Unlicensed (999) code
System Logs — set the Debug log level and stream logs

Troubleshooting Koios Troubleshoot a Connection