Troubleshooting a Device

When a device encounters a problem during its 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 connect")
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

Device Detail Page

On a device's Overview tab, the status hero banner at the top shows the current state. When a device 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.

Device List

In the device list table, each device shows a colored status icon. When a device 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 heartbeat and scan progress.

Copy errors quickly

On the device 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 device's scan cycle. When Koios reports an error code, the accompanying error message and error detail provide the specifics.

Connection Errors

Code	Name	Description
1	Failed to Connect	Koios could not establish a connection to the device. Check that the device is powered on, reachable on the network, and that connection parameters (hostname, port, credentials) are correct.

Scan Cycle Errors

Code	Name	Description
5	Failed to Read from Device	The connection was established, but Koios could not read tag values from the device. This can happen if the device becomes unreachable mid-scan, or if a tag references an invalid address or node.
6	Failed to Write to Device	Koios could not write output values back to the device. Check that output tags have valid addresses and that the device allows writes with the current credentials.
16	Failed to Validate Tags	Tag configuration could not be validated before scanning. This typically means one or more tags have invalid or missing protocol-specific settings (e.g. a Modbus tag without a register address).

Initialization Errors

Code	Name	Description
11	Failed to Initialize	The device could not complete its startup sequence. This includes loading initial tag state from the cache and preparing for the first scan.

Data Storage Errors

Code	Name	Description
7	Failed to Read Config from Database	Koios could not read the device's configuration from the database. This is rare and usually indicates a database connectivity issue.
12	Failed to Write to Model History	Tag values could not be written to the model history database (used by AI models for inference). The device itself is still scanning, but model predictions may be affected.
13	Failed to Write to Long Term History	Tag values could not be written to the time-series database. The device is still scanning and live values are available, but historical data will have a gap.
17	Failed to Write Executions	Execution metadata could not be written to the database.

Housekeeping Errors

Code	Name	Description
14	Failed to Update Heartbeat	The heartbeat counter could not be toggled after a scan. The device is still scanning normally — this error affects only the heartbeat signal that external systems may monitor.
15	Failed to Cleanup	Post-scan cleanup (resetting error states, updating status counters) did not complete successfully.

License Errors

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

Error code 0 means no error

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

Testing a Connection

You can test a device's connection without enabling it or saving configuration changes. On a device's Configuration tab, each protocol section includes a Test button.

How It Works

Open the device's Configuration tab
Fill in or edit the connection parameters (hostname, port, credentials, etc.)
Click Test — Koios attempts a one-time connection to the device using the current form values

The button shows the result:

State	Meaning
Test	Ready to test (idle)
Testing...	Connection attempt in progress
Success (green check)	Koios connected successfully
Failed (red X)	Connection failed — an error message appears below the form

Testing uses unsaved values

The test uses whatever values are currently in the form, even if you haven't saved yet. This lets you try different connection settings before committing. The test does not modify the saved configuration.

When to Test

During initial setup — verify the connection before enabling the device for the first time
After changing connection parameters — confirm the new settings work before saving
When troubleshooting — confirm whether the device is reachable on the network

How Errors Are Resolved

Errors clear automatically when the device completes a successful scan. You don't need to manually acknowledge or dismiss them — once the underlying issue is resolved (e.g. the device is back online, credentials are corrected, or a tag is fixed), the next successful scan resets the error code to None and clears the error message and detail.

If a device is stuck in a failed state:

Check the error message and error detail for specifics
Review the device's logs (on the Logs tab) for more context — set the log level to Debug for maximum detail
Verify the device's connection parameters on the Configuration tab
Use the Test button to verify the connection without enabling the device
Try toggling the device off and on with the Enabled switch

Device Parameters Tag Introduction