Troubleshoot a Connection

A connection problem starts at the device and cascades to every tag underneath it. Before you chase individual tag errors, confirm the device can reach its industrial endpoint. This is layer 1: the physical and protocol link between Koios and your PLC, sensor, controller, or OPC-UA server.

This page covers the device-level failures, the tag errors they trigger, certificate trust for secure OPC-UA connections, network reachability, and the two different Test mechanics for devices and tags (they do not work the same way — see the gotcha below).

For the three diagnostic fields (error code, error message, error detail), the full status and quality legend, the auto-clear behavior, and the master error-code lookup, see Reading Status, Quality & Errors. This page does not restate those — it goes straight to connection causes and fixes.

Errors clear on the next good scan

You never acknowledge or dismiss a connection error. Once the underlying issue is fixed, the next successful scan resets the error code to None and clears the message and detail automatically. If an error is stuck, work through the checklist in Reading Status, Quality & Errors.

Start Here: Is It the Device or the Tag?

Look at the status of the device and its tags together:

What you see	Where the problem is	Go to
Device Failed, all tags show Parent Device Failed (code 1)	The device connection — fix this first	Device won't connect
Device Running, one or a few tags Failed	Those specific tags, not the link	Tag-level failures
Device Failed with a certificate message	OPC-UA trust	OPC-UA certificate trust
A redundant tag shows No Active Device (code 109)	No device in the set is active	Redundant device sets

When every tag on a device shows Parent Device Failed, do not troubleshoot the tags — they are just reporting that their parent is down. Fix the device, and the tag errors clear on their own.

Device Won't Connect

A device in the Failed state with error code 1, Failed to Connect means Koios could not establish a link to the industrial endpoint. Work through these causes in order.

Connection-relevant device error codes

Code	Name	What to do
1	Failed to Connect	Koios could not open a connection. Check that the device is powered on, reachable on the network, and that the hostname, port, and credentials are correct.
11	Failed to Initialize	The connection opened but the device could not complete its startup sequence (loading initial tag state from the cache, preparing for the first scan). Often a transient issue — toggle the device off and on. If it persists, check the logs.
16	Failed to Validate Tags	Tag configuration could not be validated before scanning. One or more tags have invalid or missing protocol-specific settings (e.g. a Modbus tag without a register address). See Fix the offending tag below.
7	Failed to Read Config from Database	Koios could not read the device's configuration from the configuration database. This is rare and usually points at a database connectivity issue rather than the device. Check service health.
5	Failed to Read from Device	The connection was established but a read failed mid-scan. The device may have become unreachable, or a tag references an invalid address. See Bad, Missing, or Frozen Tag Values.
6	Failed to Write to Device	An output write failed. Check that output tags have valid addresses and that the device allows writes with the current credentials.

Causes of "Failed to Connect"

Wrong hostname or port. Verify the address on the device's Configuration tab. A typo, a stale IP after a DHCP lease change, or the wrong port are the most common causes. Confirm the standard port for the protocol:

Protocol	Default TCP port
OPC-UA	4840
Modbus TCP	502

The device is unreachable on the network. Use System > Network > Diagnostics to prove reachability before you touch the device config:

Ping the device's IP to confirm basic connectivity and latency.
Traceroute to see where packets are dropped or delayed if ping fails.
TCP Port Check to confirm the communication port is actually open — check port 4840 for OPC-UA or port 502 for Modbus TCP.

See Network for the full diagnostics toolset. If ping and the port check both fail, the problem is upstream of Koios — a cable, switch, VLAN, or the device being offline — not your device configuration.

A firewall is blocking the port. If ping succeeds but the TCP port check fails, a firewall (on the device, a network segment, or the host) is blocking the protocol port. Open the port or adjust the rule, then re-test.

Wrong security mode or missing certificate (OPC-UA). If the device uses Security Mode Sign or Sign & Encrypt and the server rejects the connection, it is a trust problem, not a network problem. See OPC-UA certificate trust.

Bad credentials. If the endpoint requires authentication and the connection is refused with an auth-related message, verify the username and password on the Configuration tab. For OPC-UA, confirm whether the server expects anonymous, username/password, or certificate-based authentication.

host.docker.internal is dev-only

In the local development environment, device connections to QA servers running on the host machine use host.docker.internal (e.g. opc.tcp://host.docker.internal:4840) instead of localhost. This does not apply to production. On a deployed Koios container, use the device's real hostname or IP on the plant network. Never leave host.docker.internal in a production device configuration — it will not resolve.

Failed to Validate Tags (code 16)

A device that reports Failed to Validate Tags connected successfully but has at least one tag whose protocol settings are invalid or incomplete. Koios validates every tag before it starts scanning, so one bad tag blocks the whole device.

The corresponding tag error is Configuration Error (tag code 104): 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. Find the tag with the configuration error, correct its settings on the tag's Configuration tab, and the device validation passes on the next attempt. See Bad, Missing, or Frozen Tag Values for the per-tag configuration fixes.

Tag-Level Failures

When the device is Running but individual tags fail, the connection is fine — the problem is specific to those tags. The connection-relevant tag error codes are:

Code	Name	What to do
1	Parent Device Failed	The parent device is in a failed state, so the tag cannot be collected. Not a tag problem — fix the device. Clears automatically when the device recovers.
104	Bad: Configuration Error	The tag's protocol-specific settings are invalid or incomplete (bad address, malformed node ID, missing register). Review and correct the tag's Configuration tab. This is also what drives device code 16.
102	Bad: Node Not Found	The addressed node, register, or variable was not found on the device. For OPC-UA, the namespace index or identifier may have changed — use the Browse button to re-select the correct node.
105	Bad: No Value	No value was returned. The data point may not exist, the register may be empty, or the device returned null. Confirm the tag's protocol settings point at a real data point.
106	Bad: Failed to Read	A general read failure. Common causes are invalid addresses, permission issues, or the device disconnecting mid-scan. Check the error detail for the specific exception.
109	No Active Device	The tag reads from a device set (redundancy) but no device in the set is active. See Redundant device sets.

For bad-quality reads, expression failures, mapping errors, and the range/compression issues that cause missing history, see the deeper layers: Bad, Missing, or Frozen Tag Values and Expression & Value-Mapping Errors.

The "Parent Device Failed" cascade

Every tag on a failed device inherits Parent Device Failed (code 1). This is by design: the device can't be reached, so its tags can't be collected. Do not try to fix these tags individually — navigate to the device's detail page, resolve the device error, and watch every tag clear at once on the next successful scan.

If a tag is enabled but its parent device is merely stopped (not failed), you'll see an info banner (not an error) telling you the device is stopped and the tag won't update until it is enabled and running. Enable and start the parent device to begin scanning. This is not an error condition.

Redundant device sets

A tag configured for redundancy reads from a device set rather than a single device. When it reports No Active Device (tag code 109), no device in the set is currently active — every member is disabled, stopped, or failed.

To fix it, make sure at least one device in the set is enabled and running. Open each member device and troubleshoot its connection using the Device won't connect steps above. As soon as one device comes online, the redundant tag begins reading from it and the error clears.

OPC-UA Certificate Trust

If an OPC-UA device fails to connect with a message like "Certificate rejected by server", the network is fine — the server does not trust Koios's client certificate. Certificates are only involved when the device's Security Mode is Sign or Sign & Encrypt. With Security Mode None, no certificate is used and this is not your problem.

The trust flow, in short:

In Koios, generate or upload a client certificate on the OPC-UA protocol detail page > Certificates tab, and assign it to the device (or leave it on the default certificate).
Download the Koios client certificate (.der) from the certificate's detail drawer.
Import it into the OPC-UA server's trusted certificates folder. Some servers instead move rejected certificates to a pending folder that you promote to trusted.
Trigger a fresh connection — either enable the device or click Test on its Configuration tab. Koios connects on the next scan cycle once the server trusts the certificate.

Regenerating breaks existing trust

If you regenerate or replace a certificate, every OPC-UA server that trusted the old one will reject connections until you import the new certificate into its trust list. Plan certificate changes during a maintenance window.

The exact trust process varies by server software (Kepware, Prosys, Unified Automation, Siemens, and others). See OPC-UA Certificates for the full certificate management, generation, upload, and trust workflow.

Testing a Connection

Koios can verify a connection without enabling the device or committing configuration changes. Both devices and tags have a Test button on their Configuration tab — but they behave differently, and the difference matters.

Device Test uses UNSAVED form values; Tag Test uses SAVED config

A device test connects using whatever values are currently in the form, even if you haven't saved — so you can try different hostnames, ports, or credentials before committing. A tag test uses the tag's saved configuration — so you must save any protocol setting change before testing it. Testing a tag right after editing its node ID, without saving, tests the old value.

Testing a device connection

Use this to prove the link is reachable before you enable the device.

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

The button reports the result:

State	Meaning
Test	Idle, ready to test
Testing…	Connection attempt in progress
Success (green check)	Koios connected successfully
Failed (red X)	Connection failed; an error message appears below the form

The test never modifies the saved configuration. Use it during initial setup, after changing connection parameters, and whenever you need to confirm the device is reachable on the network.

Testing a tag read

Use this to confirm Koios can actually read a value from a data point.

Open the tag's Configuration tab.
Save the protocol settings (node ID, register address, expression) — the test reads the saved values, not the form.
Click Test. Koios performs a one-time read for this tag.

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

The device must be reachable, but not enabled

A tag test connects to the device in real time using a one-time connection separate from the scan cycle. The device must be powered on and reachable on the network, but it does not need to be enabled in Koios. This lets you isolate whether a problem is the tag's configuration or the device link: if the device test succeeds but the tag test fails, the connection is fine and the tag settings are wrong.

Still Stuck?

If a device or tag stays failed after you've corrected the configuration:

Read the error message and error detail on the detail page — they carry the specific exception. Click the red error strip to copy both to your clipboard for searching logs or a support ticket.
Open the device's Logs tab and set the log level to Debug for maximum detail about the connection attempt and per-tag operations. See Logs.
Verify reachability independently with Ping and TCP Port Check in Network — this separates a Koios config problem from a plant-network problem.
Toggle the device (or tag) off and on with the Enabled switch to force a clean reconnect.
If nothing else is running either, check overall service health in Service Health & Resource Alarms.

What's Next

Reading Status, Quality & Errors: the three diagnostic fields, the status and quality legend, the stuck-error checklist, and the master code lookup
Bad, Missing, or Frozen Tag Values: layer 2 — bad quality, no value, read/write, and per-tag configuration fixes
Service Health & Resource Alarms: when nothing is running, start here
OPC-UA Certificates: generate, upload, assign, and trust client certificates
Network: ping, traceroute, DNS lookup, and TCP port check from the Koios server
Logs: set the Debug log level and stream a device's log in real time
On-Demand Scanning: trigger a manual scan outside the normal cycle
Troubleshooting Koios: the symptom router if this wasn't your problem

Reading Status, Quality & Errors Bad, Missing, or Frozen Tag Values