Edge Agent Issues
Troubleshoot common Xyte Edge agent errors, offline states, invalid host names, and proxy ID conflicts.
Diagnose common Xyte Edge agent issues.
The General tab lists individual errors and symptoms with their likely meaning. Specific use cases walks through complete diagnostic flows for scenarios that need more than a single check.
| 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: nc -zv -w 5 eu1.edge.xyte.io 4434. 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 ps2. Enter the xyte_edge container: docker exec -it xyte_edge bash3. Run docker ps again from inside the container, if applicable4. Enter the second container: docker exec -it [container_id] bash5. Run nc -zv -w 5 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 |
| Cannot read the response, check connection with the Zabbix server "zabbix-server" | The command could not be delivered to your Edge. zabbix-server is a host inside Xyte's cloud, not a port or a connection on your network. In practice it means the Edge is offline, so nothing answered. | Do not open port 10051 - it is internal to Xyte and is not reachable from outside. 1. Confirm the Edge shows Online in the portal 2. If it is not, follow Networking 3. On Docker Desktop, restart the app first - it stops when the user logs out 4. If the Edge is Online and this persists, contact [email protected] |
| 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 | An internal Xyte fault between our Zabbix frontend and our Zabbix server. zabbix-server:10051 sits inside Xyte's cloud and is not reachable from outside it - nothing on your network is involved. | No change is required on your side, and port 10051 should not be opened. Contact [email protected]. |
Port 443 tests open (nc, telnet, or Test-NetConnection succeeds) but the Edge has never connected | SSL/TLS inspection on the corporate or campus firewall. The TCP check passes, but the Edge's non-web traffic is re-signed or dropped. Xyte uses a custom certificate, which inspection breaks. | From the Edge's network, run:echo | openssl s_client -connect eu1.edge.xyte.io:443 2>/dev/null | grep "s:"Working: prints s:O=xyte, CN=server.zabbix-prodIntercepted: shows your firewall or proxy's certificate name instead, or no output at all. If intercepted, ask your network team to exempt eu1.edge.xyte.io:443 from SSL inspection. If the certificate check passes and the Edge still does not connect, send [email protected] the time of an attempt so we can trace it from our side. |
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: nc -zv -w 5 eu1.edge.xyte.io 443. A succeeded! result means outbound connectivity is fine. (telnet is not installed in the Edge container — use nc, which is.)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-worldIf 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 --shutdown4. 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). |
| The Edge is Online, but devices on a 172.17.x.x or 172.18.x.x subnet are never reachable | Those ranges overlap Docker's own default networks - docker0 uses 172.17.0.0/16 and further Docker networks take 172.18.0.0/16 onward. Traffic for the device subnet is routed to the Docker bridge instead of the physical NIC, so the devices are never reached even though the Edge itself is connected. | The tell is a ping that returns Destination Host Unreachable rather than timing out - that reply is generated locally, not by the device.1. On the Edge host run ip route get for one of the device addresses, and check whether it selects docker0 or a br-* interface instead of the real NIC2. If it does, change Docker's address pool so it no longer overlaps the device network: set default-address-pools in daemon.json (Docker Desktop: Settings, then Docker Engine) to a base outside your device ranges, for example 10.200.0.0/16 with size 243. Restart Docker and re-check the route |
Container is running but the Edge shows offline in the UI
docker ps shows xyte_edge running and the container logs look normal, but the Edge appears offline in the Xyte portal.
A running container only proves Docker started it. It says nothing about whether that container can reach the Xyte cloud. In almost every case this symptom means outbound traffic is being blocked or inspected somewhere between the host and eu1.edge.xyte.io:443.
Run the three checks below in order. Each rules out the layer before it — stop at the first failure, because everything after it fails for the same reason.
You should not need to install anything on the host. Every host command below uses a tool your operating system already provides. The one place a tool may be missing is inside the container, covered in step 3.
1. Does the name resolve?
nslookup eu1.edge.xyte.ionslookup eu1.edge.xyte.ioIf nslookup is not installed (common on minimal Linux images), use one of these instead — both are always present:
getent hosts eu1.edge.xyte.io # Linux
dig +short eu1.edge.xyte.io # Linux and macOSA healthy result returns a CNAME ending in .amazonaws.com plus an IP address. The IP is not fixed and may change over time — only successful resolution matters, never the specific address.
Non-existent domain, can't find, or no output means DNS is the problem: internal resolver, split-DNS, or a filtering appliance. Fix this before continuing.
2. Is port 443 reachable from the host?
if (Test-NetConnection eu1.edge.xyte.io -Port 443 -InformationLevel Quiet) { Write-Host "Connection successful" } else { Write-Host "Failed to connect to eu1.edge.xyte.io on port 443." }On failure this takes about 20 seconds and prints a yellow WARNING: TCP connect to ... failed line above the message. That warning is expected, not a separate error.
nc -zv -w 5 eu1.edge.xyte.io 443Success looks like:
Connection to eu1.edge.xyte.io port 443 [tcp/https] succeeded!If nc is unavailable, curl works everywhere:
curl -sv --connect-timeout 5 https://eu1.edge.xyte.io 2>&1 | head
curlwill report an SSL certificate error. That is expected and does not mean anything is broken.Port 443 on
eu1.edge.xyte.iouses a certificate issued by Xyte for Edge use only — it is not meant for browsers or general SSL tools. The line that matters isConnected to eu1.edge.xyte.io. If you see that, the port is reachable, regardless of what follows about the certificate.
3. Is it reachable from inside the container?
The container uses its own network path and can fail even when the host succeeds.
docker exec -it xyte_edge sh
nc -zv -w 5 eu1.edge.xyte.io 443nc and curl are already present in the container — nothing to install.
If you are following older instructions that use telnet, note that the Edge container runs Alpine Linux, which does not include it. Either use nc as above, or install telnet from inside the container:
apk update && apk add busybox-extrasapt and apt-get do not exist in this container — Alpine uses apk. Anything installed this way is removed whenever the container is updated or recreated.
Reading the results
| Step 1 — DNS | Step 2 — Host 443 | Step 3 — Container 443 | What it means | What to do |
|---|---|---|---|---|
| Fails | — | — | DNS is blocked or misconfigured | Check the resolver and any DNS filtering appliance |
| OK | Fails | Fails | Outbound 443 is blocked before it leaves the network | Network rules issue — see below |
| OK | OK | Fails | The host can reach the cloud but the container cannot | Docker networking: DNS in Docker Engine settings, subnet conflict, or VPN |
| OK | OK | OK | The network path is healthy | Collect Edge container logs and contact Xyte support |
If the host itself cannot reacheu1.edge.xyte.ioon port 443, this is a network-rules issue — not a Docker or Edge problem.The site firewall must permit outbound
443from the Edge host toeu1.edge.xyte.io, and any TLS inspection / HTTPS decryption must bypass*.xyte.io. Port 443 there uses a custom certificate issued by Xyte for Edge use only, and it will break under inspection.
Last updated: 2026-08-31
Updated 11 days ago