Troubleshooting Agents

Fix agents that fail to start, resolve connection loss, protect buffered data with MQTT QoS settings, and fix user registration conflicts.

Agent Fails to Start (Port Already in Use)

An agent that cannot bind one of its fixed ports stops during bootstrap and writes an error like this to its log:

{"level":50,"time":1789551934359,"pid":7,"hostname":"my-docker-compose-agent","service":"protocol-mapper","msg":"Error during bootstrap: listen EADDRINUSE: address already in use :::8888"}

The timestamp, process ID, and hostname differ in your log, and the port is 8888 for the health probe or 9184 for the metrics endpoint. Search your agent logs for EADDRINUSE.

Agents that run with host networking share the host's ports, so only the first one to start binds them. Run the agents with bridge networking. See Network Mode.

Connection Loss

When the MQTT connection between an agent and central Connectware is lost, Connectware marks the affected resources as deviated. The agent keeps its machine subscription active during the outage, so data capture from the machine continues while the broker is unreachable.

Whether buffered data reaches Connectware once the connection is restored depends on the MQTT Quality of Service (QoS) level set on each involved Endpoint:

• qos: 0 (default) — In-flight messages during the outage are lost.

• qos: 1 or qos: 2 — Incoming machine data is buffered locally on the agent and delivered once the broker is reachable again.

Configuring QoS

QoS is set per endpoint and applies separately to publishing and subscribing. To protect data flow from an agent to central Connectware, set the qos property of each involved endpoint to 1.

QoS level 2 is most likely not useful in the industry context and is not recommended here.

Tuning CybusMQ for reconnection bursts

Distributed systems must tolerate network partitions and other unexpected infrastructure failures. When clients reconnect after such a disruption, they may push their buffered messages in a short burst. To handle this reliably, configure MAX_ONLINE_MESSAGES to a value close to your expected per-client MQTT traffic so this burst is not truncated.

If you need help setting up a distributed data collection system that can tolerate longer network fragmentation, contact Cybus support at [e-mail].

User Registration Conflict (409 Conflict)

If the user registration as described above is not accepted by Connectware but lets the agent print a log message 409 Conflict, most likely there is already an existing user with the given agent name in Connectware, but with a different password. The easiest solution is to go to the “User Management” page in the Admin-UI and delete that particular user, see Deleting Users.

The full message at the agent’s log in such cases is the following:

{
  'level': 30,
  'time': 1590665714502,
  'msg': 'Failed to register agent. Response: 409 Conflict. A conflicting registration might be pending, or a user with the same username myAgent is already existing (which you must delete first).',
}