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. These are tag-level codes in the 101–109 band; they clear automatically on the next successful scan.

Symptom	Code	Name	What to do
Read failed — a node/register that doesn't exist, a read the device or server refuses, or a failure partway through the scan	106	Bad: Failed To Read	Koios could not get a reading for this tag. The error detail names the cause: the node may not exist on the server, a permission error, the device dropping the point mid-scan, or, for OPC-UA, the server's status name and code, such as `BadNodeIdUnknown` for a node that does not exist or `BadUserAccessDenied` for a read the server does not permit. An OPC-UA bad status that gives no specific reason also reports here. If the address may have moved, re-select it with the Browse button on the tag's Configuration tab — a namespace index or identifier may have changed.
OPC-UA server reports the data itself bad	107	Bad: Read Quality	The server answered but reports that the value cannot be used: a sensor or device failure, a point out of service, a value out of range, lost communication between the server and its own data source, or a configuration problem on the server or its data source. The error detail gives the status name, its low or high limit, and the status code, and quotes any value the server sent with it, which Koios does not use. Fix it at the source (the instrument, the device, or the server's link to it), not in the tag's configuration. A status saying the server is waiting for its first value normally clears within a few scans.
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, the device returned null, or an OPC-UA server marked the reading good or uncertain but sent no value. 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.
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 bad Modbus register type, data type, or bit position, a malformed OPC-UA node ID, an invalid BOSS variable code). Review and correct the Configuration tab. Only this tag is affected — the device keeps reading the rest.
Tag was never read at all, and shows no error	—	—	A Modbus tag with no register configured is skipped from the read entirely and logs a warning on the device rather than raising a tag error. Set the register on the Configuration tab.

While a tag's read is failing it has no value, so nothing that uses the tag receives its last good reading. The tag list, the tag's Overview tab, and dashboard value widgets still show that reading, set apart from a current value, with how long ago it was taken, so you can see what the tag read before it failed. The value returns with the next successful read.

An uncertain OPC-UA reading keeps running, with a warning

If an OPC-UA server marks a reading uncertain, Koios keeps the value and the tag stays Running with error code 0. The tag's quality is the server's full status name, such as UncertainLastUsableValue or UncertainEngineeringUnitsExceeded, and the tag shows a warning naming that status and, when the server reports one, the low or high limit the value has reached. The warning shows while the server keeps marking readings uncertain; while the device is reconnecting, a held reading shows the reconnect notice instead. Check the field device or server health for that node when the warning persists.

Readings beyond the engineering range

How an over-range reading appears depends on how the server reports it. A server that marks it uncertain keeps the tag running with the value and a warning naming the limit. A server that marks it bad fails the tag with code 107 and an out-of-range status in the error detail, because a bad status carries no usable value. Many servers and control systems can be configured to report over-range as uncertain instead; change that on the server if you want those readings collected.

Modbus: one tag fails while its neighbours read fine

Koios reads contiguous registers in a single request, up to the device's Max Registers Per Read setting (1–125, default 125), and many gateways and older controllers reject a block larger than their own limit. When a block fails, Koios re-reads its tags one at a time and keeps every value the device returns, so only an address that genuinely cannot be read reports code 106. The failing block's address range and size are written to the device log; size Max Registers Per Read against that range on the device's Configuration tab — see Troubleshoot a Connection.

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. Code 108 (Mapping Error) routes there, as does an expression tag failing with code 106 and the message Failed to evaluate expression.

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. On a Modbus TCP device this code instead means the device answered none of the scan's reads. That is usually a connection problem — see Troubleshoot a Connection — but a wrong Unit ID, a Timeout shorter than the device needs to reply, or tags that all point at addresses the device ignores rather than rejects give the same code, so check those when the device is reachable.
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	The tag-validation pass itself failed while the device was starting up. This is rare and is not how a single misconfigured tag reports itself — a bad tag raises its own code `104` and the device keeps collecting every other tag. Check the device's logs for the underlying exception.

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, not a per-tag fault; it shows as a warning message on the group's status rather than an error code. 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. History-write failures are reported on the parent device, not the tag — look for device code 13 Failed To Write to Long Term History, which means live values are still 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 (code 108, and expression failures under code 106)
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