Troubleshooting

Symptom → cause → fix for the issues admins hit most. When in doubt, start with the agent log and confirm the machine can reach app.verops.io.

The agent starts but the estate stays empty

Symptom: the agent log shows successful reports, but nothing appears in Products.
Cause: in targeted mode the group's patterns match nothing currently running — report [full]: 0 apps is expected.
Fix: confirm the agent's group has rulesets attached with patterns that match your apps, or run a short discovery sweep to see everything.

The service is running but nothing is happening

Symptom: the service is RUNNING (the v0.3.0 and later installers always register and start it), but the log shows configuration or authentication errors on repeat.
Cause: the agent is installed but not yet configured — by design it idles and retries until it has credentials.
Fix: set backend_url plus an enrollment_token in scout.toml, then restart the service — the config is read once at startup.

The service will not start at all after an upgrade to v0.6.x

Symptom: the service stops immediately after every start attempt. The log carries a configuration error naming scout.toml and one or more of api_key, username, password; the process exit code is 78 (EX_CONFIG).
Cause: Scout v0.6.0 removed the org-wide ingest key and the user-login credential. A configuration that still names one is refused rather than silently ignored — presence is enough, so even api_key = "" triggers it. This is by far the most common upgrade failure.
Fix: re-deploy the machine from Inventory → Agents → "Deploy Scout" (the package carries a valid enrollment token, no legacy keys, and the machine re-enrols keeping its identity), or hand-edit scout.toml: delete the offending lines, add an enrollment_token, and restart. The message also lists any SCOUT_API_KEY / SCOUT_USERNAME / SCOUT_PASSWORD environment variable that supplied a value — clear those too. A machine you have not migrated yet can stay on Scout v0.5.0 or earlier, which keeps working against the platform unchanged. See Enrollment and device credentials.

The agent can't authenticate

Symptom: the agent log shows authentication failures instead of successful reports.
Cause: an invalid, expired, exhausted, or revoked enrollment token, or a revoked device credential. From v0.6.0 an org-wide ingest key is refused for a Scout by the platform even when the key itself is valid — Scout identifies itself with an X-Agent-Kind: scout header and inventory ingest declines API-key auth from it. On the Machine Agent, the platform connection key cannot authenticate inventory.
Fix: mint a fresh enrollment token under Inventory → Agents → Deploy Scout and restart the agent — or simply re-deploy the machine, which re-enrols it. If the device's credential was revoked deliberately, re-enroll it with a new token (a rejected device key makes the agent re-enroll automatically when its configured token is still valid).

A machine enrolled with the wrong token, or landed in the wrong group

Symptom: a freshly deployed machine reports an enrollment token that "doesn't work", or it appears in Inventory → Agents under a group nobody chose.
Cause: on preconfigured builds before v0.6.1 the service could come up on the packaged template's placeholder token and group before the installer's configuration was applied. The two symptoms have the same single cause.
Fix: download a fresh package from Inventory → Agents → "Deploy Scout" — v0.6.1 restarts the service after writing your configuration, so the agent enrols with your token and joins your group on the first attempt. Re-running it on an affected machine re-enrols it and keeps its identity and history.

Inventory surfaces are unavailable

Symptom: the Inventory screens or dashboards are blocked or missing for the org.
Cause: the operator inventory feature is disabled for the organization.
Fix: an operator enables the Inventory feature for the organization.

Bandwidth columns are always 0

Symptom: rx/tx bytes are blank for every app.
Cause: on Windows, per-app bandwidth (IPv4 + IPv6 TCP) needs Administrator — an unelevated agent logs one warning and reports 0. On Linux it is read from kernel tcp_info via ss; if ss (iproute2) is missing the sampler degrades to 0 with one log line.
Fix: on Windows run elevated (the installed service is; a hand-run agent needs a highest-privilege task). On Linux install iproute2. Note the figures are a TCP-only lower bound — UDP/QUIC is not counted and loopback is excluded, so 0 for a purely-UDP app is expected.

Apps never reach activity level 3 (focused)

Symptom: usage looks understated; nothing is ever "focused".
Cause: the agent runs in a non-interactive session (session 0), so there is no foreground window to detect.
Fix: run the agent in the user's interactive console session — register it as a logon task with onlogon + highest.

A central-config change didn't take effect

Symptom: you changed a group's rulesets or the collection policy but the agent still behaves the old way.
Cause: agents pick up central changes on their next poll, not instantly.
Fix: wait about a minute; confirm the applied config line in the agent log updates. A failed check keeps the last-known-good config (it never reverts).

A local scout.toml edit didn't take effect

Symptom: you edited scout.toml but the running agent ignores it.
Cause: the local config file is read once at startup.
Fix: restart the service — sc stop VerOpsScout & sc start VerOpsScout on Windows, sudo systemctl restart verops-scout on Linux.

New software isn't showing up

Symptom: a freshly installed app never appears.
Cause: targeted mode only tracks matching patterns; genuinely new software is invisible until a discovery sweep.
Fix: run discovery for the group, classify the new title from the Review queue, and promote it into a ruleset.

Note: The agent is resilient: every failure is logged and it keeps running. Undelivered usage is folded into the next successful report, so a transient outage costs no data.

Update posture shows "Unknown"

Symptom: a host's Update posture reads Unknown rather than current, behind or critical.
Cause: the agent predates the module (Scout v0.4.0 / Machine Agent v0.3.0), the patch posture module is switched off in the policy that applies to that host's group, the refresh has not run yet (default every 6 hours), or the host is macOS — which is not supported in this release and always reads Unknown.
Fix: confirm the agent version (the binary self-reports it, e.g. verops-scout --version), check the module is enabled under Inventory → Policy, and restart the service to force a scan at startup. Unknown is never an error state — VerOps deliberately never scores an unmeasured machine as Current. See Update posture.

An agent is not taking the update

Symptom: a release channel is enabled with a non-zero rollout percentage, but agents stay on the old version.
Cause: the endpoint half of the switch is off, the agent is outside the rollout, or there is no artifact to hand out. Auto-update needs both an enabled channel and auto_update = true on the endpoint, and the platform only offers a version it has a checksummed download for.
Fix: read the reason on the agent's row in Inventory → Agents → Auto-update. Not enabled / Halted are policy; Outside the canary or Outside the rollout (0%) means raise the percentage; Up to date means there is nothing to do. If the row says the agent is being offered but nothing happens, check the agent log — an endpoint that has not opted in logs one line saying the offer was ignored because auto_update is false in scout.toml. Remember the local config is read once at startup, so restart the service after editing it. See Automatic updates.

An update reported "failed" or "rolled back"

Symptom: the attempt trail in the Auto-update dialog shows Failed or Rolled back for a host.
Cause: Failed means the attempt stopped at one of the pre-swap checks — a download error, a size or SHA-256 mismatch, an artifact that is not an executable for that platform, or a staged binary that would not run and report the expected version. Rolled back means the swap happened but the new binary could not complete a report, so the previous one was restored.
Fix: the detail column carries the exact reason. In both cases the host keeps a working agent — on Failed the installed binary was never modified, and on Rolled back the previous release is back in place — so there is nothing to repair on the endpoint. Halt the rollout if several hosts report the same failure, and check the agent log (journalctl -u verops-scout -f, or the Windows service log) for the endpoint-side message.