Troubleshooting

Symptom › Cause › Fix

The agent never reaches "Connected"

Cause: a wrong connection_key, a URL/port that doesn't point at the backend on 9191, or outbound traffic blocked by a firewall or security group.

Fix: verify reachability, then re-check the key and URL.

curl -v http://your-verops-server:9191/api/machine/agents/authenticate
# run the agent with --log-level debug to see auth attempts and payloads

Connected, but no heartbeat metrics refresh

Cause: you're within the first heartbeat interval, or the host is non-Linux.

Fix: wait one interval (default 30 s). On Windows, cpu_usage and memory_mb report 0.0 by design — all other functionality works.

A log read returns no results

Cause: the agent user can't read the file, the filePath is wrong, the file exceeds max_file_size_mb, or the patterns match nothing.

Fix: confirm read access (ls -la the path), verify the exact case-sensitive path, raise the size limit if the file must be read, and test the regex independently.

The Windows service won't start

Cause: the service was registered against a pre-0.2.0 console binary, or the binPath lacks the --service flag — the Service Control Manager then times out (error 1053).

Fix: upgrade to v0.2.0+ (Resources → Downloads) and register with install-service.cmd or the "Add agent" PowerShell snippet — the binPath must run machine-agent.exe --service --config … --log-file …. The service is registered with automatic start and failure recovery; check C:\Program Files\VerOps\machine-agent.log for startup errors.

Inventory not appearing though the agent is Connected

Cause: the inventory module authenticates separately — the machine connection key does not authorize it.

Fix: give the module its own credential — an enrollment token (enrollment_token, minted under Inventory → Agents → Deploy Scout; exchanged automatically for a per-device key) or an ingest api_key (ta_live_…), which the Machine Agent still supports. See the inventory module and how the agent communicates.

Inventory stopped after a config clean-up

Cause: the api_key was removed from [inventory] — usually while applying the Scout v0.6.0 enrollment-only migration to the wrong agent. Scout refuses to start with an api_key; the Machine Agent needs a credential and stops reporting inventory without one.

Fix: put the credential back — either the api_key as it was, or better, an enrollment_token minted under Inventory → Agents → Deploy Scout — and restart the service. The Machine Agent is unchanged in v0.5.0; the Scout migration does not apply to it.

A server is not taking the update

Cause: auto-update needs both an enabled release channel and auto_update = true under [inventory] in config.toml; the server may also be outside the rollout percentage, already on the channel's version, or waiting on an artifact VerOps has not published a checksummed download for yet. A Machine Agent with [inventory] disabled has no update channel at all.

Fix: read the reason on the agent's row in Inventory → Agents → Auto-update. An opted-out server logs one line saying the offer was ignored because auto_update is false — the config is read at startup, so restart the service after editing it. See Automatic updates.

An update reported "failed" or "rolled back"

Cause: Failed means the attempt stopped at a pre-swap check — download error, 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 an inventory report, so the previous one was restored.

Fix: nothing on the host — on Failed the installed binary was never modified, and on Rolled back the previous release is already back in place. The detail column carries the exact reason; halt the rollout if several hosts report the same one, and check journalctl -u verops-machine-agent (or C:\Program Files\VerOps\machine-agent.log) for the host-side message.