Bad, Missing, or Frozen Tag Values

Use this article when a device is Running but one of its tags is wrong: the value is missing, flagged bad quality, non-numeric, or clearly incorrect. Because the connection is up, the problem is almost always specific to that one tag's address, data type, or the value it reads back, not the device or the network.

If every tag on the device is failing, or the device itself is Failed, start one layer up at Troubleshoot a Connection instead.

Read the tag's three diagnostic fields first

Every tag records an error code, error message, and error detail, plus a quality string and a status. Those fields tell you what failed and where. This article assumes you already know how to read them — see Reading Status, Quality & Errors for the shared explainer, the status/quality legend, the full code lookup, and the auto-clear/stuck checklist.

First: is the device actually stopped?

If a tag is enabled but its parent device is stopped, the tag's overview shows a blue info banner (rather than a red error) telling you the device is stopped and the tag won't update until the device is enabled and running. This is not a tag error. The tag has nothing to read because its device isn't scanning. Enable and start the parent device, and the tag will begin collecting on the next scan. Only continue with the codes below once the device is Running.

Symptom → cause → code

When the device is Running but the tag reads bad, match the symptom to the tag error code. All of these are tag-level codes in the 100–110 band; they clear automatically on the next successful scan.

Symptom	Code	Name	What to do
Bad OPC-UA quality (server returned a non-Good status)	107	Bad: Read Quality	The read succeeded but the source reported poor quality (e.g. `Uncertain` or a `Bad_*` OPC-UA status). The value may be stale or unreliable. Check the field device / OPC-UA server health for that node.
Node / register / variable not found on the device	102	Bad: Node Not Found	The addressed node ID, register, or variable doesn't exist on the device. Re-select it with the Browse button on the tag's Configuration tab — a namespace index or identifier may have changed.
No value / empty register / null response	105	Bad: No Value	The protocol returned nothing for this tag. The data point may not exist, the register may be empty, or the device returned null. Verify the address and data type on the Configuration tab.
Value came back but isn't a number	103	Bad: Not a Number	The device returned text, a special character, or an unexpected type where a numeric value was expected. Fix the configured data type so it matches what the device actually returns.
Read fails partway through the scan	106	Bad: Failed To Read	A read operation for this tag failed (invalid address, permission issue, or the device dropped this point mid-scan). The error detail carries the underlying exception.
Output write to the device failed	101	Bad: Failed To Write	Koios could not write an output value back. Confirm the address is writable, the credentials allow writes, and the value is within the device's accepted range.
Address, data type, register, bit position, or node ID is wrong	104	Bad: Configuration Error	The tag's protocol-specific settings are invalid or incomplete (e.g. a Modbus tag with no register or bad bit position, a malformed OPC-UA node ID, an invalid BOSS variable code). Review and correct the Configuration tab. This usually surfaces at device initialization.
General bad-quality condition, no better fit	100	Bad: General	A catch-all bad-quality state. Read the error detail for specifics.
Unexpected failure processing the tag	2	Generic Exception	An unhandled exception occurred while processing the tag. The error detail contains the specific exception.

Wrong value, not a bad-quality flag?

If the tag reads a good value that is simply wrong — off by a factor, inverted, or in the wrong units — the collection is fine and the problem is in a transform. That's a value-mapping or expression issue, not a read error. See Expression & Value-Mapping Errors. Codes 108 (Mapping Error) and 110 (Bad: Expression) also route there.

Isolate it with a Test read

You can attempt a single read for one tag without enabling it. On the tag's Configuration tab, each protocol section has a Test button.

Open the tag's Configuration tab and save any changes (Test uses the tag's saved configuration, unlike the device connection test which uses the live form values).
Click Test. Koios performs a one-time read from the device for this tag.

State	Meaning
Test	Idle, ready to test
Testing...	Read attempt in progress
Success	A value was read; the result message shows the value returned
Failed	The read failed; an error message appears below the form

The device must be powered on and reachable, but it does not need to be enabled in Koios — the test uses a one-time connection separate from the scan cycle. A Success here with a Failed state during scanning points at scan timing or an intermittent device, not the tag config.

The device-side view of a bad tag

A single misconfigured tag can also raise an error on the device, because the device is what performs the read and write:

Code	Name	What it means for the tag
5	Failed To Read from Device	The connection is up but a tag read failed — often a tag pointing at an invalid address or node. Check which tag is failing and correct its address.
6	Failed To Write to Device	An output write failed. Verify the output tag's address is writable and the credentials permit writes.
16	Failed To Validate Tags	One or more tags have invalid or missing protocol settings (e.g. a Modbus tag with no register), caught before scanning. Fix the flagged tag's Configuration tab.

If instead the tag shows code 1 Parent Device Failed, the device itself is down and the tag can't be collected until it recovers — troubleshoot the device at Troubleshoot a Connection. Code 109 No Active Device (redundancy: no device in the set is active) also belongs there.

Overscanning starves reads

If the device is Running with a Warning strip and tags update sluggishly or intermittently, the scan group may be overscanning — execution is taking longer than the configured scan rate, so reads fall behind. That's a scan-group timing problem (scan-group error 1, Overscan), not a per-tag fault. See Service Health & Resource Alarms.

Live value updates but history is flat or gappy

If a tag's live value is moving but Trends show flat lines or far fewer points than expected, the read is fine and the issue is historization, usually a mismatch between the tag's Range Min / Max and the compression settings. See Data Is Stale, Frozen, or Has Gaps and Tag Range and Compression. A code 200 Failed To Historize on the tag means the live value is available but that period will have a gap in historical storage.

If a tag stays stuck

Tag errors clear on the next successful read or write — you don't acknowledge them manually. If a tag won't recover once the device is Running:

Read the error message and error detail for the specific cause.
Set the device's log level to Debug and review its logs for tag-level detail.
Verify the tag's protocol settings on the Configuration tab (address, data type, register, bit position, node ID).
Use Test to attempt a single read and see if the error reproduces.
Toggle the tag off and on with the Enabled switch.

For the shared stuck-tag checklist and how auto-clear works across all entities, see Reading Status, Quality & Errors.

What's Next

Reading Status, Quality & Errors — the shared diagnostic-fields reference, status/quality legend, and master code lookup
Troubleshoot a Connection — when the device is Failed or every tag reads Parent Device Failed
Expression & Value-Mapping Errors — when the value reads good but is transformed wrong (codes 108, 110)
Data Is Stale, Frozen, or Has Gaps — when live values update but history or Trends don't
Service Health & Resource Alarms — overscanning scan groups and service health
Tag Value Mapping and Tag Expressions — the transforms that own the mechanics
System Logs — set Debug level and stream device logs
Tag Range and Compression — how the tag range drives historization

Troubleshoot a Connection Expression & Value-Mapping Errors