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, or an OPC-UA reading the server marks uncertain). Behavior is normal; the amber strip flags attention.
Testing	Violet	A manual test-output override is active (test mode). Overrides the normal status display.

Only three statuses are stored

Running, Stopped, and Failed are the only persisted states. Starting, Stopping, Warning, and Testing are computed in the interface from those three plus context — you will not find them as distinct values in exports or the API.

An enabled entity showing Stopped, with no spinner

An enabled entity normally shows Starting until it comes up. If its parent device or scan group is disabled, it shows the plain Stopped label instead — no spinner — because it is genuinely idle rather than spinning up. Enable the parent and the entity picks up on the next cycle.

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	Meaning
Good	Successful read; the value is trustworthy.
Bad	The read failed or the value could not be used, reported together with a tag error code.
OPC-UA status name	A running OPC-UA tag carries the server's full status name, such as `Good`, `GoodClamped`, `UncertainLastUsableValue`, or `UncertainEngineeringUnitsExceeded`. A reading the server marks bad fails the tag with a quality of `Bad`. A reading the server marks uncertain that then fails, for example because it is not a number, keeps its uncertain status name.

An uncertain OPC-UA reading is a warning, not an error

When an OPC-UA server marks a reading uncertain, Koios keeps the value, records the status name as the tag's quality, and shows a warning naming the status and any low or high limit the value has reached. No error code is raised and the tag keeps running. A bad status fails the tag: code 107 — Bad: Read Quality when the server reports the data itself bad, and 106 — Bad: Failed To Read for any other bad status or a read exception. See Bad, Missing, or Frozen Tag Values.

Quality is not the same as an error code

Quality describes the most recent reading; the error code describes the failure. A read that fails sets both, such as quality Bad with code 106 or 107, but a reading can carry a non-Good quality with no error code at all.

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. Whenever the entity carries an error message, a red error strip appears below the hero with the message and detail. Click it to copy. The strip follows the error field, not the status, so it also appears on an entity that is not Failed — a model held back by an invalid configuration is left Stopped and still shows the strip. See Model Configuration Errors.
A failed tag's last reading: a failed tag's row in the tag list, its Overview tab, and dashboard value widgets show the reading it last took, set apart from a current value, with how long ago it was taken. Hover over it for the time it was taken and that reading's quality. It appears alongside the failed status and error, never in place of them, and it is not a current value: a tag whose own read failed has no value for anything that uses it until it reads again.
List tooltips: in list tables, each row shows a colored status icon. Hovering it displays that entity's error message as a tooltip. The icon is usually red, but an errored entity that is not Failed keeps the icon its status earns — a stopped-but-enabled model shows the grey spinner and still carries the message.
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.

Reserved codes

These tables are the platform's complete code space, and some values are reserved — defined so exports and the API have a stable meaning for them, but not currently reported by any service. Reserved rows are marked as such and have no cause or fix, because they cannot appear on a live entity. If you are hunting a code you saw in the product, it will be one of the linked rows.

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	Reserved — not currently reported
11	Failed to Initialize	Connection
12	Failed to Write to Model History	Reserved — not currently reported
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	Reserved — not currently reported
999	Unlicensed	Licensing

Tag Error Codes

Code	Meaning	Where to go
0	None — value is good	—
1	Parent Device Failed	Connection
2	Generic Exception	Reserved — not currently reported
100	Bad: General	Reserved — not currently reported
101	Bad: Failed to Write	Tag Values
102	Bad: Node Not Found	Reserved — not currently reported
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	Reserved — an expression failure reports code 106 instead
200	Failed to Historize	Reserved — a history write failure reports device code 13
999	Unlicensed	Licensing

Model Error Codes

Code	Meaning	Where to go
0	None — operating normally	—
1	No File Given	Reserved — not currently reported
2	No File Found	Models
3	Failed to Parse File	Reserved — not currently reported
4	Failed to Get Model Depth	Reserved — not currently reported
5	Failed to Get Bindings	Reserved — not currently reported
6	Bindings Invalid State	Models
7	Failed to Structure History	Reserved — not currently reported
8	Failed to Get Predictions	Reserved — not currently reported
9	Binding Prediction Index Missing	Models
10	Failed to Scale Predictions	Reserved — not currently reported
11	Failed to Write Predictions	Models
12	Thread Error	Reserved — not currently reported
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	Reserved — not currently reported
7	Failed to Structure History	Reserved — not currently reported
8	Prediction Index Missing	Models
9	Failed to Scale Prediction	Models
10	Failed to Write Prediction	Reserved — not currently reported
11	Binding Tag Disabled	Models
12	Binding Tag Bad Quality	Reserved — not currently reported
13	Binding Tag Failed	Models
14	Binding Tag Not Assigned	Models
15	Binding Not in Dictionary	Reserved — not currently reported
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	Reserved — overscan is reported as a warning, not an error code
2	On-Demand Read Failed	Services & Alarms
3	On-Demand Write Failed	Reserved — not currently reported
99	Generic Exception	Reserved — not currently reported

Scan groups have no license code

Scan groups do not report 999 — Unlicensed. In practice the only code a scan group reports is 2 — On-Demand Read Failed; overscanning shows as the amber Warning state with a message on the group's status rather than as an error code.

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