---
title: "Troubleshoot a Connection"
description: "Fix a device that won’t connect and the tags that fail with it"
source_url: https://ai-ops.com/docs/troubleshoot/connection
---

# 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](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md). This page does not restate those — it goes straight to connection causes and fixes.

> [!NOTE] 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](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md).

## 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-wont-connect) |
| Device **Running**, one or a few tags **Failed** | Those specific tags, not the link | [Tag-level failures](#tag-level-failures) |
| Device **Failed** with a certificate message | OPC-UA trust | [OPC-UA certificate trust](#opc-ua-certificate-trust) |
| A redundant tag shows **No Active Device** (code 109) | No device in the set is active | [Redundant device sets](#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](#failed-to-validate-tags-code-16) 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](https://ai-ops.com/docs/troubleshoot/tag-values.md). |
| 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](https://ai-ops.com/docs/system/network.md) 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](#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.

> [!WARNING] 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](https://ai-ops.com/docs/troubleshoot/tag-values.md) 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](#device-wont-connect). 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](#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](https://ai-ops.com/docs/troubleshoot/tag-values.md) and [Expression & Value-Mapping Errors](https://ai-ops.com/docs/troubleshoot/expressions-and-mapping.md).

### 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](#device-wont-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:

1. 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).
2. **Download** the Koios client certificate (`.der`) from the certificate's detail drawer.
3. **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.
4. 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.

> [!WARNING] 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](https://ai-ops.com/docs/protocols/opc-ua-certificates.md) 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.

> [!CAUTION] 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.

1. Open the device's **Configuration** tab.
2. Fill in or edit the connection parameters (hostname, port, credentials, security mode).
3. 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.

1. Open the tag's **Configuration** tab.
2. **Save** the protocol settings (node ID, register address, expression) — the test reads the saved values, not the form.
3. 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 |

> [!TIP] 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:

1. 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.
2. 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](https://ai-ops.com/docs/system/logs.md).
3. Verify reachability independently with **Ping** and **TCP Port Check** in [Network](https://ai-ops.com/docs/system/network.md) — this separates a Koios config problem from a plant-network problem.
4. Toggle the device (or tag) off and on with the **Enabled** switch to force a clean reconnect.
5. If nothing else is running either, check overall service health in [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md).

## What's Next

- [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md): the three diagnostic fields, the status and quality legend, the stuck-error checklist, and the master code lookup
- [Bad, Missing, or Frozen Tag Values](https://ai-ops.com/docs/troubleshoot/tag-values.md): layer 2 — bad quality, no value, read/write, and per-tag configuration fixes
- [Service Health & Resource Alarms](https://ai-ops.com/docs/troubleshoot/services-and-alarms.md): when nothing is running, start here
- [OPC-UA Certificates](https://ai-ops.com/docs/protocols/opc-ua-certificates.md): generate, upload, assign, and trust client certificates
- [Network](https://ai-ops.com/docs/system/network.md): ping, traceroute, DNS lookup, and TCP port check from the Koios server
- [Logs](https://ai-ops.com/docs/system/logs.md): set the Debug log level and stream a device's log in real time
- [On-Demand Scanning](https://ai-ops.com/docs/devices/on-demand-scanning.md): trigger a manual scan outside the normal cycle
- [Troubleshooting Koios](https://ai-ops.com/docs/troubleshoot/introduction.md): the symptom router if this wasn't your problem