# Troubleshoot devices

> What the connection test results, device statuses, sleep mode, tag errors and error codes mean, and what to check for each.

Source: https://proxus.io/docs/troubleshoot/devices

This page explains the messages Proxus shows when it cannot read a device or a tag, and what to check for each.
Read it from the top when a device does not connect; jump to [Tag errors](#tag-errors) when only some values are
wrong.

## The connection test

**Test the connection** in the device setup wizard runs on the gateway you picked, so it proves what the gateway
can reach, not what your own computer can. It runs these steps in order and stops at the first failure:

| Step | Shown when it passes | What it checks |
| --- | --- | --- |
| Network | `<address>:<port> reachable from the gateway` | The gateway opens a TCP connection to the device. |
| Session | `Protocol session opened` | The device accepts the protocol's session (for OPC UA, SNMP, MTConnect, Haas and Heidenhain this is the only step). |
| Identity | `Device identity read` | Siemens S7 only: the CPU's order number, shown as `The device says it is <...>.` |
| Test read | a value next to each tag | Each tag is read once (at most 64 tags). |

When the network step fails, the test also says whether the address is on one of the gateway's own networks:
`<address> is not on any of the gateway's networks (<networks>). The gateway needs a route to it, or the address is
wrong. Behind NAT (for example a gateway in Docker) this can be normal.`

### Test results

| Result | Meaning | What to check |
| --- | --- | --- |
| `<gateway> did not answer.` | The gateway is offline or too old to run the test. | That the gateway shows **Online** in **Edge Gateways**. See [Gateways](https://proxus.io/docs/troubleshoot/gateways). |
| `The gateway cannot reach the device.` | No TCP connection: wrong address, wrong port, the device is off, or a firewall or VLAN is in between. The detail says `Failed to connect to <host>:<port>` or `Connection to <host>:<port> timed out after <n> ms`. | The IP address and port. From the gateway's host, try to reach the device (`ping`, or a TCP test to the port). Firewall rules between the gateway's network and the device. |
| `The device refused the session.` | The network is fine, but the device did not accept the protocol. | For Siemens: rack and slot, and that the CPU allows **PUT/GET communication from remote partner**. For others: the protocol settings (unit ID, station number, security mode), and that the device is not limited to one client already connected. |
| `No answer in time.` | The device or gateway did not finish within the test time (10 seconds plus time for the test read). | A slow network, a busy device, or the wrong protocol variant for this device. |
| `The connection settings are incomplete.` | For example `The device address (Host) is empty.` | Fill in the address. |
| `This gateway cannot test this protocol yet; you can still save the device.` | The gateway has no test for this protocol. | Save the device and watch its status. |
| `The test did not succeed.` | Any other error. The detail is the driver's message. | Read the detail; see [Error codes](#error-codes). |

### Test read errors

| Message | Meaning |
| --- | --- |
| `The address is empty.` | A tag has no address. |
| `Invalid address format for selected protocol: <address>` | The address does not fit the protocol's form, for example `40001` where Modbus expects `x=3;0`. |
| `Data type <type> cannot be test-read.` | That type is read in normal operation but not in the test. |
| `No answer.` | The device did not return this value. |

## Device status

The device list and the device page show one status per device:

| Status | Meaning | What to check |
| --- | --- | --- |
| **Connected** | The gateway reads the device and values arrive. | |
| **Warning** | Connected, but some tags fail. The status text counts the tags that are OK, Bad and Disabled. | The failing tags, see [Tag errors](#tag-errors). |
| **Sleep Mode** | The device stopped answering, and the gateway now only tries it now and then. | See [Sleep mode](#sleep-mode). |
| **Offline** | No fresh values. `Offline/Stale, Last telemetry: <time>` or `Last known issue: <status>`. | The last error shown. |
| **Gateway Offline** | `Gateway '<name>' is not connected`. The device may be fine; its gateway is not. | [Gateways](https://proxus.io/docs/troubleshoot/gateways). |
| **Disabled** | The device is switched off in Proxus. | Turn it on if it should run. |
| **Unknown** | `No status data available` yet, for example just after saving. | Wait a read cycle. |

A device counts as offline when no value arrived within a window that depends on how often it is read: at least
90 seconds, normally two and a half read intervals.

## Sleep mode

When a device fails ten read cycles in a row (three for a Siemens S7 that cannot connect), the gateway stops
reading it on every cycle and puts it in sleep mode. Its status becomes:

```text
Sleep Mode - Last Error: Device Offline - Timeout (Device, High confidence, Code: COMM_TIMEOUT_001) - Device at 10.20.4.37 is not responding within the expected time.
```

The text after `Last Error:` is the last error with its category, scope, confidence and code, then a plain
explanation. In sleep mode the gateway tries one read after 10 seconds, then waits twice as long after each
failure, up to 5 minutes (`[Fieldbus] SleepProbeIntervalMs` and `SleepProbeMaxIntervalMs`). The first successful
read ends sleep mode and normal reading starts again. Saving the device's settings also ends it at once.

So a device in sleep mode recovers by itself once it answers again. Fix the cause given in the last error; you do
not need to restart anything.

## OPC UA device stopped after the upgrade

An OPC UA device that uses **Sign** or **Sign & encrypt** connected before 2.0.0 but sends no data now, and the
gateway reports `BadCertificateUntrusted`. Since 2.0.0 the gateways accept only the server certificates that the
Certificate Store trusts; trust given locally on a gateway before 2.0.0 no longer counts.

1. Go to **Security > Certificate Store** and open **Trust View**, **Rejected**.
2. Find `OPC UA server <name> (<address>)`, compare its fingerprint with the one on the server, and select **Trust**.

All gateways take the change within a minute, and the device connects at its next retry. Devices with the security
mode **None** are not affected. See [Connect an OPC UA server](https://proxus.io/docs/connect/devices/opc-ua).

## Melsec A1E ASCII or XINJE device does not connect

Before 2.0.0, **Mitsubishi Melsec A1E ASCII** devices used the wrong protocol and could not connect, and the
**XINJE TCP** and **XINJE Serial Over TCP** drivers were swapped. This is fixed in 2.0.0 with no change to your
settings. If such a device still fails, check its address and port as for any device.

## Tag errors

A tag that cannot be read does not stop the rest of the device. Its value shows the error instead:

```text
[Error 2/5] Wrong data type (DB10.DBW4, Float): Configured data type does not match the returned device value width. [Code: COMM_TYPE_001; Scope: Tag; Confidence: High]
```

| Part | Meaning |
| --- | --- |
| `[Error 2/5]` | The second failure in a row. After five, the tag is disabled. |
| `[Disabled after <n> errors]` | The tag is disabled: it is no longer read on each cycle, only retried once a minute, and its quality is **Uncertain**. The number keeps counting the failed retries. |
| `Wrong data type (...)` | The category of the error, then the tag's address and data type. |
| the text after `:` | What went wrong. |
| `[Code: ...; Scope: ...; Confidence: ...]` | See [Error codes](#error-codes). |

A disabled tag comes back by itself after one successful read, or at once when you save the device's settings.

For Siemens S7, Modbus and OPC UA, Proxus recognizes common mistakes and says so directly, for example:

- `S7 Bool tags should use DBX bit addresses, not DBW word addresses.`
- `S7 Int/UInt/Float values are typically 4 bytes. Use DBD or change the data type.`
- `The PLC reports that the requested DB address does not exist.`
- `Modbus Bool tags should usually use coil/discrete input areas, not holding/input registers.`
- `The Modbus address format is invalid. Expected patterns are like x=3;100 for holding registers.`
- `OPC UA node ids should use formats like ns=2;s=TagName or ns=3;i=1001.`
- `The OPC UA server does not recognize this node id.`

### Wrong values but no error

The read succeeds but the number is wrong:

- **Far too large or tiny numbers** (for example `1.0836943E-38` for a current): the data type or the byte order
  does not match the device. Check the type (`Float` against `Int`) and the profile's byte order setting.
- **Off by one register**: datasheets count from 1, the protocol from 0. In Proxus, `40001` means holding register
  0 (`x=3;0`).
- **Value in the wrong unit or scale**: set the unit on the tag, or scale it in a
  [pipeline](https://proxus.io/docs/reference/pipeline-nodes#calculate).

### Quality

| Quality | Set when |
| --- | --- |
| **Good** | The value was read without error. |
| **Bad** | The read failed for this tag; an OPC UA server reported bad quality; an SNMP object has no value; an MTConnect condition is `Fault`. |
| **Uncertain** | The tag is disabled after repeated errors; an MTConnect or SNMP item reports `UNAVAILABLE`; an MTConnect condition is `Warning`; an OPC UA server reported uncertain quality. |

`UNAVAILABLE` from an MTConnect agent means the agent is running but has no value for that data item, often because
the machine is off. It shows as a read error with code `COMM_GEN_001`.

## Error codes

Each error has a code. The general codes:

| Code | Category | Typical cause | What to check |
| --- | --- | --- | --- |
| `COMM_TIMEOUT_001` | Timeout | The device did not answer in time. | The device is on and not overloaded; the network; the read interval is not shorter than the device can answer. |
| `COMM_CONN_001` | Connection refused | The device refused the connection. | Power, the port, a firewall on the device, another client holding the only connection. |
| `COMM_SOCKET_001` | Network unreachable | No route to the device. | IP address, subnet, VLAN, routing. |
| `COMM_SOCKET_002` | Device unavailable | The device closed the connection. | The device restarted or limits connections. |
| `COMM_SOCKET_003` | Timeout | The connection was closed while reading. | Usually follows a restart of the device or the network; it recovers by itself. |
| `COMM_ADDR_001` | Invalid address | The address has the wrong form. | The address format of the protocol. |
| `COMM_TYPE_001` | Wrong data type | The value does not fit the tag's type. | The data type against the device's memory map. |
| `COMM_RANGE_001` | Out of range | The address or length is outside the device's memory. | Block sizes and start offsets. |
| `COMM_DATA_001` | Wrong data type | The value could not be converted. | The data type. |
| `COMM_AUTH_001` | Authentication failed | The device refused the credentials. | User name, password, certificates. |
| `COMM_DEVICE_001` | Device unavailable | The device answered with no data. | The device's state and the address. |
| `COMM_UNKNOWN_001` | Unknown | The driver reported an unknown error. | The full message in the device log. |
| `COMM_GEN_001` | Read error | Any message Proxus does not recognize. | The text before the code. |

Protocol-specific codes name the protocol:

| Codes | Examples |
| --- | --- |
| `COMM_MODBUS_001` to `004` | Function code not supported by the device, address out of bounds, checksum error, not a Modbus answer. |
| `COMM_S7_001` to `004` | DB larger than 255 bytes in one read, PUT/GET access turned off in the CPU, object does not exist, read exceeds the PLC's setting. |
| `COMM_OPCUA_001` to `003` | Unknown node ID, session invalid, server not connected. |
| `COMM_AB_001`, `002` | Tag does not exist, controller out of memory for the answer. |
| `COMM_MELSEC_001` to `003`, `COMM_OMRON_001`, `002`, `COMM_OMRONCIP_001`, `002` | Unsupported read, checksum failure, connection limit reached, wrong header, tag not found. |
| `COMM_BECKHOFF_001` to `004` | Target not found or no route (check the AMS route), service not supported, symbol not found, symbol download failed. |
| `COMM_SNMP_001` to `003` | No such object, wrong community string, answer too big. |
| `COMM_MTCONNECT_001` to `003` | Device not found in the agent, component not found, probe or current request failed. |
| `COMM_FANUC_*`, `COMM_HAAS_*`, `COMM_HEIDENHAIN_*`, `COMM_KUKA_*`, `COMM_YRC_*`, `COMM_ESTUN_*` | Machine or robot not ready, not in automatic mode, servo off, variable or parameter not found, access denied. |
| `COMM_PANA_*`, `COMM_FATEK_*`, `COMM_FUJI_*`, `COMM_KEYENCE_*`, `COMM_YOKO_*`, `COMM_GESRTP_*`, `COMM_LSIS_*`, `COMM_VIGOR_*`, `COMM_MEMOBUS_*`, `COMM_TOYO_*`, `COMM_DELTA_*`, `COMM_XINJE_*`, `COMM_INOVANCE_*`, `COMM_TURCK_*`, `COMM_MEGMEET_*`, `COMM_ER7BC_*` | The same categories for these vendors: address, checksum, access, device state, protocol. The message before the code is specific. |

When the message is not clear, the gateway's log has more: for serious errors it lists suggested checks, such as
`Verify device is powered on and operational` or `Check subnet and VLAN configuration`. Open
[System logs](https://proxus.io/docs/administer/system-logs) and filter by the gateway.

## Related

- [Protocols](https://proxus.io/docs/reference/protocols): default ports and capabilities.
- [Add a device](https://proxus.io/docs/connect/devices/add-a-device)
- [The device page](https://proxus.io/docs/connect/devices/device-page)