Troubleshooting

Start with the log. Under systemd:

journalctl -u infrality-agent -n 100 --no-pager

It exits at start-up

the API rejected this agent's credentials (HTTP 401) — the key is mistyped, revoked or expired. Check ingestor.api_key, and in the organization’s API keys that the key is still active. Keys expire after a year by default.

That API key is bound to a different agent (HTTP 403) — the key is single-agent and already belongs to another machine, or this machine’s hostname changed after a rebuild. Create a new key for this machine. See API keys.

The configuration cannot be parsed — the log names the file. A duplicated key is enough. Fix it; the agent will not start on defaults rather than sweep the wrong network.

This API key is not accepted from this machine's address (HTTP 401) — the organization only accepts its keys from certain IP ranges. Ask an admin to add the public address this machine leaves by. See security policy.

It runs but never shows online

• No route to api.infrality.io:443. curl -sI https://api.infrality.io/health from the machine. A proxy that blocks WebSockets breaks the live channel: the agent then falls back to HTTPS for its results, but shows as offline between sweeps.
• The machine’s clock is far off, and TLS fails. Fix time synchronisation.
• The organization is scheduled for deletion. Its API keys are refused.

The board stays empty

• The agent is not attributed to the board. The log says so at start-up: the API refused part of this agent's configuration. Choose the board in the agent’s settings on the dashboard, or fix ingestor.project_id. See connect it.
• Nobody started a sweep. The default is to sweep only when asked. Press Scan, or set a repeat interval.
• It swept the wrong range. A range the machine has no route into finds nothing. The dashboard’s range field offers the networks the machine is really on.
• The board is in the trash. The sweep is recorded but not drawn, and the API says so.

It finds the router and nothing else

The ping sweep has no capability. Look for operation not permitted in the log, or a rising infrality_icmp_errors_total.

systemctl show infrality-agent -p AmbientCapabilities   # should list cap_net_raw
getcap /usr/local/bin/infrality-agent                    # when run by hand

Re-run the installer to restore the unit, or sudo setcap cap_net_raw+ep $(which infrality-agent). On macOS run it with sudo; on Windows from an Administrator terminal.

Every sweep ends Partial

The sweep reaches its time limit. The configuration file the packages install says timeout: 15s; raise it to 90s in the file or set Time limit per sweep on the dashboard. A larger value costs a fast network nothing: it is a ceiling, not a duration.

Hosts have no name

Nothing on the network named them. In order of effect:

1. Set your read-only SNMP community in discovery.snmp_community — switches, routers, printers and firewalls then name themselves.
2. Register DHCP leases in DNS, so reverse lookups return real names.
3. Name them on the board. A name your team typed is never overwritten by a sweep.

See naming hosts.

Hosts have no MAC or manufacturer

• They are past a router. ARP stops at the first router; only NetBIOS reports a MAC from further away. Put an agent on that segment.
• The ARP sweep fell back to the neighbour table — on macOS and Windows always, on Linux without CAP_NET_RAW. MACs still appear for hosts the system has spoken to.
• The manufacturer is missing but the MAC is there: install your distribution’s ieee-data package (or arp-scan), and the agent reads the full registry.

A device appears twice

The same machine was drawn from two sources that share no address or MAC — an import and a sweep, for instance. Merge them on the board. A sweep matches by id, address and MAC; an imported machine is matched by its declared address when that address is inside the swept range.

The router is drawn at the wrong address

It is marked assumed: the machine’s default route is outside the swept range, so the first usable address was used. Sweep the range the machine is on, or correct the router on the board.

Settings changed on the dashboard do not stick

They apply from the next sweep, never the one running. Under the service, the agent writes them back into /etc/infrality-agent/config.yaml; an install older than the current unit mounted that folder read-only. Re-run the installer.

Still stuck

Collect journalctl -u infrality-agent -n 300, the agent’s version and topology.json from /var/lib/infrality-agent/, and write to us through the contact page.