Documentation menu

Troubleshooting

The handful of things that actually go wrong, an agent that never appears, a test with no data, and loss that is not loss.

Start with the symptom, then follow the evidence. Keep the affected agent, target and time window together.

Agent missing: check registration and the service.
Test exists but has no results: confirm it is enabled, its placement resolves to an agent, and the time window includes a scheduled run. Then inspect the agent’s recent status and logs.
One location is slow: compare the same target from another vantage point before changing the target configuration.
A hop reports loss: read trust qualifiers and compare downstream behavior before treating that hop as the fault.
The assistant cannot connect: check the account model in AI & MCP. For external clients, verify your personal token, endpoint and scope in Assistant and MCP.

Most problems fall into one of a few shapes.

The agent never appears in the portal

The agent registers itself the first time it tries to ship data, so a host that is running but silent has usually failed at one of three points.

Check the service is running.

Linux

systemctl status routespear-agent
journalctl -u routespear-agent -n 50

macOS

sudo launchctl print system/com.routespear.agent

Windows

Get-Service RouteSpearAgent
Get-Content "$env:ProgramData\RouteSpear\Agent\agent.log" -Tail 50

Check it can reach the ingest endpoint. Outbound TLS to the address in the agent’s configuration has to be permitted. This is the common one, and it is almost always egress filtering or a proxy rather than anything about RouteSpear.

Check the pack was still valid. An enrollment token is single-use and expires after 24 hours. A pack that has already installed one machine, or that sat in a folder since yesterday, will not enrol; mint a fresh one from the portal.

An agent that cannot reach the control plane is not idle, incidentally. It starts measuring and buffers results to disk, and ships the backlog once the path clears. Fixing connectivity an hour later usually fills the gap in rather than leaving one.

An agent appears but has no data

Check the Tests tab on the agent. If it is empty, no check has been assigned to it, a test created with a specific agent selected goes only to that agent.

If checks are assigned and still produce nothing, look at the capability report. A check whose capability is absent does not run. See capabilities.

A path shows loss in the middle but the target is fine

This is the most frequently misread pattern in network monitoring, and it is usually not a fault.

Routers commonly deprioritise or rate-limit their responses to probe traffic while forwarding real traffic perfectly. The result is a hop showing alarming loss with every subsequent hop healthy, including the destination.

Loss at a hop that does not continue to the following hops is a property of that router’s control plane, not of your path. Real loss propagates: if traffic is genuinely being dropped at hop 6, hops 7 onward see it too.

RouteSpear marks these hops as uncertain rather than drawing them as solid, so the picture matches reality. The trust model explains the markings.

Latency looks wrong on one host

Check the agent’s Resources tab first.

A host short of CPU adds its own scheduling delay to every measurement it takes, and that delay is indistinguishable from network latency in the result. Before investigating a network that appears to have slowed, confirm the instrument is not the thing that changed.

Also check the egress address on the agent overview. An agent whose traffic started leaving through a different interface or a VPN is measuring a different path than it was yesterday.

A Windows host cannot see multi-path routing

Inspect the selected transport and recorded flow control first. The Windows helper API has no flow-identifier control and runs one discovery trace. Available raw ICMP and TCP transports can provide stronger control, but even full flow control does not guarantee that a small sample reveals every branch.

Confirm the installer’s inbound ICMP firewall rule is present and that the agent has the privileges its transport needs. Detection checks whether replies actually arrive. New portal path checks require TCP/full and are refused when that instrument is unavailable. A width of one, especially over ICMP, is not proof of a single route. See agent capabilities and the Path Health guide.

Wireless data is missing or stale

On Linux without cap_net_admin, the agent cannot trigger an active scan and degrades to reading the last cached scan, which may be minutes old. Grant the capability for live scanning.

On recent macOS the underlying scan tool was removed by Apple and the capability is absent entirely. Use a Linux host for wireless measurement.

Getting diagnostics

The capability report is the single most useful thing to collect: