Troubleshooting a Tag

When a tag encounters a problem during its device's scan cycle, Koios records three pieces of diagnostic information:

Error Code — a category that identifies what kind of failure occurred
Error Message — a short description of the problem (e.g. "Failed to read tag")
Error Detail — additional context, typically the underlying exception or system message that caused the failure

Together, these three fields tell you what went wrong, why, and where to start investigating.

Where Errors Appear

Tag Detail Page

On a tag's Overview tab, the status hero banner at the top shows the current state. When a tag is in a Failed state, a red error strip appears below the status showing the error message and error detail. You can click this strip to copy the full error text to your clipboard.

If the tag also has an info message (a non-error status note), it appears as a separate blue strip below the error.

In the tag list table, each tag shows a colored status icon. When a tag has failed, hovering over the red icon displays the error message as a tooltip.

Parameters Tab

All three error fields — error code, error message, and error detail — are also visible in the Parameters tab under the Live Data section, alongside other real-time values like the tag's current value and timestamp.

Copy errors quickly

On the tag detail page, click the error strip to copy both the error message and error detail to your clipboard. This is useful when sharing diagnostics or searching logs.

Error Codes Reference

Each error code corresponds to a specific stage in the tag's read/write cycle. When Koios reports an error code, the accompanying error message and error detail provide the specifics.

Parent Device Errors

Code	Name	Description
1	Parent Failed	The tag's parent device has failed, so the tag cannot be scanned. Check the device's own error for the root cause — once the device recovers, this tag error clears automatically.

General Errors

Code	Name	Description
2	Exception	A general exception occurred during tag value read or write. The error detail will contain the specific exception message. This is a catch-all for unexpected failures that don't fit a more specific error code.

Read Errors

Code	Name	Description
105	No Value	The protocol returned no value for this tag. This can happen if the data point doesn't exist on the device, the register is empty, or the device returned a null response. Check that the tag's protocol settings (node ID, register address, etc.) are correct.
106	Read Failed	Koios could not read this tag's value from the device. This is a general read failure — the error detail will contain the specific exception. Common causes include invalid addresses, permission issues, or the device disconnecting mid-scan.
107	Read Quality Bad	The value was read but the data source reported poor quality. For OPC-UA tags, this means the server returned a quality status other than "Good" (e.g. Bad, Uncertain). The value may be stale or unreliable.

Write Errors

Code	Name	Description
101	Write Failed	Koios could not write an output value back to the device. Check that the tag address is valid for writing, that the device allows writes with the current credentials, and that the value is within the device's accepted range.
102	Bad: Node Not Found	The OPC-UA node referenced by this tag does not exist on the server. Verify the node ID on the tag's Configuration tab — the namespace index or identifier may have changed. Use the OPC-UA browser to re-select the correct node.

Value Errors

Code	Name	Description
103	Not a Number	The tag received a value that cannot be converted to a number. This happens when the device returns text, a special character, or an unexpected data type where a numeric value was expected.

Configuration Errors

Code	Name	Description
100	General Error	A general tag error occurred that doesn't fit a more specific category. Check the error detail for more context.
104	Configuration Error	The tag's protocol-specific settings are invalid or incomplete. This typically appears during device initialization — for example, a Modbus tag without a register address, an OPC-UA tag with a malformed node ID, or a BOSS tag with an invalid variable code. Review the tag's Configuration tab and correct the settings.

Expression Errors

Code	Name	Description
110	Expression Error	A calculation tag's expression failed to evaluate. This can be caused by syntax errors in the formula, division by zero, referencing tags that don't exist, or circular dependencies between expression tags. Review the expression on the tag's Configuration tab.

Mapping Errors

Code	Name	Description
108	Mapping Error	The tag's value mapping or transformation failed. This is set by the mapping service when it encounters an error processing this tag's mapped value. Check the tag's mapping configuration and ensure the mapped source is valid.

Redundancy Errors

Code	Name	Description
109	No Active Device	This tag is configured for redundancy (reading from a device set), but no device in the set is currently active. Check that at least one device in the device set is enabled and running.

Data Storage Errors

Code	Name	Description
200	History Failure	The tag's value could not be written to the time-series database. The tag is still being scanned and its live value is available, but historical data will have a gap for this period.

License Errors

Code	Name	Description
999	Unlicensed	The tag cannot be scanned because the Koios license does not cover it. This happens when the number of enabled tags exceeds the license limit. Disable unused tags or upgrade your license.

Error code 0 means no error

An error code of 0 (None) means the tag has no active error. You'll see this on healthy tags or after an error has been resolved.

Common Scenarios

Tag failed but device is running

If the device is running but an individual tag is in a failed state, the problem is specific to that tag — not the connection. Common causes:

Wrong address — the tag's node ID, register address, or query points to something that doesn't exist on the device. Use the Browse button on the Configuration tab to re-select the correct data point.
Data type mismatch — the configured data type doesn't match what the device is actually returning. Try a different data type in the protocol settings.
Permission denied — the device credentials don't have permission to read or write this specific data point.

All tags on a device failed

If every tag on a device shows Parent Failed (error code 1), the problem is at the device level. Navigate to the device's detail page and troubleshoot the device error first — see Troubleshooting a Device.

Tag shows "Device is stopped"

If a tag is enabled but its parent device is stopped, you'll see an info banner on the tag's overview: "Device is stopped — Tag will not be updated until device is enabled and running." This isn't an error — enable and start the parent device to begin scanning.

Tag is not historizing properly

If a tag's live value is updating but Trends show flat lines or far fewer recorded points than expected, the cause is almost always a mismatch between the tag's Range Min / Max and the compression settings.

Koios uses Swinging Door Trending (SDT) to compress historical data. SDT calculates a tolerance band as a percentage of the tag's configured range — not the actual value. If the range is left at the default 0–100 but the tag only moves between 0 and 1, the tolerance band is wider than the entire signal and almost nothing gets recorded.

How to fix it:

Set the tag's Range Min and Range Max to match the actual expected value range (e.g. 0–1, not 0–100)
Review the global Compression Deviation in System > Retention > History Compression — 1–2% is a good starting point
If only this tag needs special treatment, enable Override global compression settings on the tag's Configuration tab and set a tighter deviation or disable compression for this tag alone
To disable compression globally, turn off the Compression Enabled toggle on the Retention page

Check the range on every tag

The default range of 0–100 causes silent data loss for tags with narrow value bands (0–1, 4–20 mA, 0.0–5.0). This is the most common cause of missing historical data. See Tag Range and Compression for a full explanation of how SDT interacts with the tag range.

Testing a Tag

You can test whether Koios can read a value from a tag without enabling it. On a tag's Configuration tab, each protocol section includes a Test button.

How It Works

Open the tag's Configuration tab
Ensure the protocol settings are saved (node ID, register address, expression, etc.)
Click Test — Koios performs a one-time read from the device for this tag

The button shows the result:

State	Meaning
Test	Ready to test (idle)
Testing...	Read attempt in progress
Success (green check)	Koios read a value — the result message shows the value returned
Failed (red X)	Read failed — an error message appears below the form

Testing uses saved configuration

Unlike device connection tests, tag tests use the tag's saved configuration. Make sure you save any protocol setting changes before testing.

The device must be reachable

The tag test connects to the device in real time. The device must be powered on and reachable on the network, but it does not need to be enabled in Koios. The test uses a one-time connection separate from the scan cycle.

When to Test

After creating a tag — verify the protocol settings are correct before enabling
After using a device browser — confirm the auto-populated settings read the expected value
When troubleshooting — isolate whether the problem is with the tag's configuration or the device connection

How Errors Are Resolved

Tag errors clear automatically when the tag is successfully read or written on the next scan. You don't need to manually acknowledge or dismiss them — once the underlying issue is resolved (e.g. the address is corrected, the device recovers, or the expression is fixed), the next successful scan resets the error code to None and clears the error message and detail.

If a tag is stuck in a failed state:

Check the error message and error detail for specifics
Review the device's logs — set the device's log level to Debug for maximum detail about tag-level operations
Verify the tag's protocol settings on the Configuration tab
Use the Test button to attempt a single read and see if the error reproduces
Try toggling the tag off and on with the Enabled switch

Value Mapping Model Introduction