WireGuard Client Status API: Peer Data Issue
Hey there! If you're using the WireGuard Client add-on in Home Assistant and have stumbled upon some trouble with the status API, you're in the right place. Specifically, we're going to dive into an issue where the peers data in the API response seems a bit… off. Let's break down what's happening, why it matters, and what you can do about it. The issue primarily affects those who are using the WireGuard Client 0.27 on Home Assistant 2025.11.2 and later versions. It involves the data format received from the status API, which causes problems for any integrations or sensors relying on that data. Let's start with a basic understanding of the problem.
The Core Problem: Malformed Peer Data
So, what's the deal? The WireGuard Client's status API is designed to give you a snapshot of your VPN's current state. This includes information about connected peers, data transfer, and more. When you query the API, you expect a structured JSON response. However, there's a problem: the peers field, which should be an array (a list of peer details), is showing up as a string. This misformatting causes all sorts of issues when you try to parse the data in Home Assistant, especially when you are using restful sensors to read the data. Instead of being able to easily access the details for each peer (like their endpoint, latest handshake, transfer statistics, and uptime), you're essentially getting a string that looks like a JSON array, but isn't actually one.
To better understand, consider the expected format. It should look something like this:
{
"peer_count" : 1,
"peers" : [
{
"endpoint": "[2001:...:...:...:...:...:...:...]:51820",
"latest_handshake": "2025-11-18T19:51:54Z",
"transfer_rx": 8089752,
"transfer_tx": 39490016,
"uptime_seconds":89
}
],
"status" : "connected",
"timestamp" : 1763495603,
"total_traffic_rx" : 8089752,
"total_traffic_tx" : 39490016
}
Notice the peers field contains an array of objects. Each object represents a peer with its specific details. This structure allows Home Assistant to easily parse and use the information to create sensors, display statuses, and more. However, the actual response looks like this:
{
"peer_count" : 1,
"peers" : "[{\"endpoint\":\"[2001:...:...:...:...:...:...:...]:51820\",\"latest_handshake\":\"2025-11-18T19:51:54Z\",\"transfer_rx\":8089752,\"transfer_tx\":39490016,\"uptime_seconds\":89}]",
"status" : "connected",
"timestamp" : 1763495603,
"total_traffic_rx" : 8089752,
"total_traffic_tx" : 39490016
}
In this example, the peers field is a single string that contains the JSON-formatted peer data. This difference, though subtle, creates big problems when you want to access individual peer data within your Home Assistant setup. The fix involves correcting the data structure so it aligns with what Home Assistant expects. So, when your Home Assistant setup attempts to parse the peers data, it fails. This is because it's trying to treat a string like an object, which is impossible.
Symptoms and Impact of the Malformed Data
If you're experiencing this issue, you'll likely notice several symptoms that indicate something's not quite right. These symptoms directly stem from the inability of your Home Assistant sensors or integrations to properly interpret the malformed peer data. Let's explore these symptoms, because they provide a clear indication that you're facing this specific issue. Firstly, you will see Template Variable Warnings in Your Home Assistant Logs. If you're using template sensors or any other Home Assistant components that rely on accessing the peer data, you'll start seeing a lot of template variable warnings in your Home Assistant logs. These warnings typically look like this: Template variable warning: 'str object' has no attribute 'peer_1' or similar errors, depending on how your templates are set up. These errors clearly indicate that the code is trying to access a specific peer (e.g., peer_1), but it cannot find the expected object. This is because the entire peers data is being treated as a single string, and not as an array of peer objects. Secondly, incorrect sensor values or missing data. As your sensors can't parse the peer data correctly, any sensors designed to display peer-specific information (like the peer's uptime, data transfer, or last handshake time) will either display incorrect values or show up as unavailable. For example, a sensor showing the uptime of a specific peer might always read as '0' or show 'Unknown' or 'Unavailable'. This is because the sensor is unable to correctly extract the information from the malformed peers data. In addition, the dashboards and automations won't function as intended. Because the sensor data is either inaccurate or missing, any dashboards or automations that depend on this information will fail. For example, if you have an automation that sends a notification when a peer disconnects, it won't trigger because the automation can't accurately detect the peer's status. All of these symptoms stem from the same root cause: the peers data not being in the expected format. Fixing this will require modifying how the API responds, or how you parse its response in Home Assistant.
Troubleshooting Steps and Workarounds
If you've identified that you're facing this issue, you can implement the following troubleshooting steps to diagnose the problem effectively. First, verify the API response. You can directly query the WireGuard Client's status API to confirm the malformed data. Use a tool like curl to make a GET request to the API endpoint. For example, run this command in your terminal: curl http://fd24a922-wireguard-client:51821/. Check the API response in a web browser or using curl. This allows you to inspect the raw JSON data and confirm that the peers field is indeed a string. Once you have the raw data, manually inspect the returned JSON to confirm that the peers field is formatted as a string rather than an array of JSON objects. Then, review your Home Assistant configuration. Double-check your Home Assistant configuration for any restful sensors, template sensors, or other integrations that access the WireGuard Client status data. Look at the configurations of the sensors that use data from the WireGuard Client. Make sure the JSON paths and any template logic are correct for the expected JSON format (array of objects), rather than a string containing a JSON-formatted array. Finally, modify the template to parse the string. The simplest workaround, at least temporarily, is to modify your template sensors or other integrations to correctly parse the string. This can involve using json.loads() in your template to convert the string into a valid Python object (a list of dictionaries). By implementing these troubleshooting steps, you can accurately confirm the issue. If you use the steps above, you can often work around the malformed data until a more permanent fix is available. Keep in mind that these workarounds may require adjusting how you process the data within your Home Assistant setup. The key is to correctly parse the string-formatted peer data into a usable JSON format.
Potential Solutions and Fixes
Now, let's explore some of the potential solutions to fix this malformed peer data. First, the most straightforward approach would be to update the WireGuard Client Add-on. The ideal solution is a fix directly within the WireGuard Client add-on itself. The add-on developers could correct the format of the peers data in the API response. This ensures that the data is correctly structured as an array of JSON objects. The add-on needs to be updated to generate the correct format for the peers field. To facilitate this, you can submit an issue on the add-on's GitHub repository or other support channels. This helps alert the developers to the problem and provides the context they need to implement the fix. You can contribute to this process by checking for updates regularly. Check the official add-on repository for updates. As soon as a corrected version is available, update the add-on within your Home Assistant instance. Once you do this, your sensors should resume functioning correctly. Next, you can make changes to your Home Assistant configuration. In this case, you can modify your Home Assistant configuration to handle the malformed data correctly. You can use a template sensor to parse the string into a usable JSON format. This involves using the json.loads() function within your template to convert the string into an array of JSON objects. This approach allows you to work around the issue. To implement this, modify your existing template sensors or create new ones to account for the string format of the peers data. Here's a basic example of how you might adapt a template sensor:
- platform: template
sensors:
wg_peer_uptime:
friendly_name: "WireGuard Peer Uptime"
value_template: >-
{% try %}
{% set peers = states.sensor.wireguard_status.attributes.peers | from_json %}
{% if peers and peers[0] %}
{{ peers[0].uptime_seconds }}
{% else %}
0
{% endif %}
{% except %}
0
{% endtry %}
unit_of_measurement: "seconds"
In this example, the from_json filter transforms the string into a list of dictionaries. You can then access the uptime_seconds of the first peer. Remember to adapt the specific paths and indices based on the structure of your data. The goal is to correct the data format within your Home Assistant setup, allowing it to correctly read peer information. Finally, report the issue to the developers. Reporting the issue directly to the developers is important. This ensures that the problem is acknowledged and addressed. You can report the issue on the Home Assistant forums or through the add-on's GitHub repository. When reporting, provide clear details about the issue. In addition, include the version of WireGuard Client and Home Assistant you're using. Provide a sample of the malformed data and describe the steps you've taken. The key takeaway is to choose a solution based on your comfort level and the available resources. You can apply these potential solutions to overcome the malformed peer data issue. Remember, the best approach is to address the root cause, which is the data format generated by the WireGuard Client add-on.
Conclusion: Staying Ahead of the Curve
Dealing with the malformed peer data issue requires understanding the root cause, identifying the symptoms, and implementing appropriate fixes. By understanding the problem and trying different solutions, you can keep your Home Assistant setup running smoothly. Always stay informed about updates to the WireGuard Client and Home Assistant. Keep an eye on the official channels for announcements and fixes. With these steps, you'll be well-equipped to handle the malformed peer data issue. This proactive approach will help you maintain a robust and functional Home Assistant setup.
For more information, visit the official Home Assistant Community Forums to get help and to be part of the community.
