> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/data-flows/agents/troubleshooting-agents.md).

# Troubleshooting Agents

## 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](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md#qos) to `1`.

{% hint style="warning" %}
QoS level 2 is most likely not useful in the industry context and is not recommended here.
{% endhint %}

{% hint style="info" %}

## 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`](/2-4-2/broker/cybusmq/environment-variables.md) to a value close to your expected per-client MQTT traffic so this burst is not truncated.
{% endhint %}

If you need help setting up a distributed data collection system that can tolerate longer network fragmentation, contact Cybus support at **<support@cybus.io>**.

## 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](/2-4-2/access/user-management/users.md#deleting-users).

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

{% code lineNumbers="true" %}

```yaml
{
  '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).',
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-2/data-flows/agents/troubleshooting-agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.