Edge Agent Issues

Diagnose common Xyte Edge agent issues using the table below.

Scenario or error	Likely meaning	Recommended next steps
Edge agent is in error	Host offline, device offline, or required traffic is blocked.	Check: 1. Docker container status (running, restarting, exited) 2. Network connectivity from the host 3. Network connectivity from inside the container: `telnet eu1.edge.xyte.io 443` 4. Restart the Docker container If it still fails: 1. Remove Docker and reinstall it 2. Reinstall the Edge software again (fresh install)
Edge agent: Invalid params: invalid host name	The Edge ID format is wrong, or the value includes a hidden character or quote.	Try this: 1. Re-enter the Edge ID manually 2. Remove any extra quotes or hidden characters 3. Try the request again
Edge agent is offline	Start with offline troubleshooting, then verify outbound connectivity.	Start here: - Review the guide: Edge offline troubleshooting Then run these checks: 1. Run `docker ps` 2. Enter the `xyte_edge` container: `docker exec -it xyte_edge bash` 3. Run `docker ps` again from inside the container, if applicable 4. Enter the second container: `docker exec -it [container_id] bash` 5. Run `telnet eu1.edge.xyte.io 443`
Edge agent: Proxy ID already exists	The proxy ID is already attached to another Edge device.	Next steps: 1. Delete the Edge agent in the UI that is currently using this proxy ID 2. After the old ID is released, add the Edge again with the same proxy ID
Connection to Zabbix server "zabbix-server:10051" failed. Possible reasons: 1. Incorrect "NodeAddress" or "ListenPort" in the "zabbix_server.conf" or server IP/DNS override in the "zabbix.conf.php"; 2. Incorrect DNS server configuration. Operation timed out	The Docker container cannot reach the Zabbix server on port 10051	Verify that the Zabbix server is running and listening on 10051, and confirm that the container can resolve and connect to zabbix-server over the network. If your'e using Docker Desktop try first to restart the app
Testing connectivity with `curl` returns `SSL: certificate subject name 'server.zabbix-prod' does not match target hostname 'eu1.edge.xyte.io'` (curl error 60)	Expected and harmless. `eu1.edge.xyte.io:443` is a mutual-TLS data channel that authenticates by certificate subject (`server.zabbix-prod`), not by DNS host name, so host-name verification in general-purpose tools such as `curl` or a browser fails even though the secure connection itself succeeds. It is not a misconfiguration of the Edge, the network, or Xyte.	No action needed if the Edge shows Active / Online — it is working. To test connectivity, check port reachability instead of the certificate: `telnet eu1.edge.xyte.io 443`. A `Connected to ...` result means outbound connectivity is fine. You can also run `curl` with the `-kv` flags to skip certificate validation: `curl -kv` . If the output shows `Connected to eu1.edge.xyte.io`, the connection is established and the Edge is working as expected. Do not add certificate exceptions or change the Edge / proxy configuration based on this warning.
Updating the Edge version reports success in the hub, but the agent stays on the old version. Docker logs show `failed to resolve reference "docker.io/xytetech/edge_proxy:<tag>"` followed by `EOF` (or a similar timeout / connection reset while pulling the image)	Docker could not reach Docker Hub to download the new Edge image, so the pull failed and the agent rolled back to the previous version. This is almost always host network connectivity — a firewall, proxy, SSL inspection appliance, or corporate network policy blocking Docker Hub — not the Xyte image itself.	Confirm it's the network, not the image: 1. Pull a public test image: `docker pull hello-world` If this also fails, the problem isn't specific to the Xyte image. 2. Test Docker Hub reachability: `curl -I` A `401 Unauthorized` response is expected and confirms Docker Hub is reachable. 3. On Docker Desktop for Windows, restart Docker Desktop. If it continues, fully close it, run this in PowerShell, then reopen Docker Desktop: `wsl --shutdown` 4. If it still fails, ask your network or security team whether a firewall, proxy, SSL inspection, or corporate network policy is blocking Docker Hub (`registry-1.docker.io` and `auth.docker.io` on port 443).

What’s Next