Troubleshoot the agent
This page covers the agent problems that come up most: a computer that does not enroll, an installer that refuses to run, and an endpoint that stops reporting. Start with the checks below, which rule out most causes in a minute.
Check first
Section titled “Check first”-
Check that the agent service is running.
On Windows:
Terminal window Get-Service OutpostAgent, OutpostWatchdogOn Linux:
systemctl status outpost-agent. On FreeBSD:service outpost_agent status. On OpenBSD:rcctl check outpost_agent. On macOS:sudo launchctl print system/com.outpost.agent. -
Read the last lines of the agent’s log. Most failures name their cause there. See Where the logs are.
-
On a Windows, Linux, or macOS computer with the tray app, open it and select Device Info. While the agent is disconnected, the Connection line says why, for example DNS lookup failed: the server name could not be resolved.
Where the logs are
Section titled “Where the logs are”| Platform | Agent log |
|---|---|
| Windows | C:\ProgramData\Outpost\logs\agent.log, with watchdog.log and helper.log beside it. If the file cannot be written, the agent logs to the Windows Application event log under the source OutpostAgent. |
| Windows installer | outpost-setup.log in the temporary folder of the account that ran outpost-agent-setup.exe |
| Linux | The systemd journal: journalctl -u outpost-agent |
| FreeBSD | /var/log/outpost-agent.log |
| OpenBSD | syslog, under the daemon facility |
| macOS (Preview) | /var/log/outpost-agent.log |
To log more detail, set the environment variable OUTPOST_LOG_LEVEL to
debug for the agent and restart it. On Linux, add
OUTPOST_LOG_LEVEL=debug to /etc/default/outpost-agent. Set it back to
info when you are done.
Cause: the enrollment token was refused
Section titled “Cause: the enrollment token was refused”An installer’s token enrolls a limited number of computers within a limited time. A default installer enrolls one computer within 24 hours. A token that has expired, has been used up, or belongs to another client is refused.
How to confirm it
Section titled “How to confirm it”The agent log repeats a line like this:
enrollment REJECTED - the bootstrap token is invalid, expired, or for another client; generate a fresh installer if this persistsA token from an installer issued for another client also shows this installer was issued for a different client. The agent keeps retrying, so the endpoint
never appears in the console.
Resolution
Section titled “Resolution”- Download a new installer, or a staged rollout installer for many computers, from Enroll a device, choosing the right site.
- Run it on the computer. On a computer where the agent is already installed,
you can instead apply the new
agent.jsonwithoutpost-agent import-config, or enroll with a token. See Deploy the agent at scale.
Cause: the plan’s endpoint limit is reached
Section titled “Cause: the plan’s endpoint limit is reached”Each plan limits how many endpoints you can enroll. Home Lab allows up to 15 managed endpoints and Essentials up to 50. During a free trial, Enterprise and MSP allow up to 100. See Plans and limits.
How to confirm it
Section titled “How to confirm it”When you select Issue token only, the panel shows Plan limit reached with a message that names the limit and the next plan:
Home Lab includes 15 endpoints. Upgrade to Essentials to add more.During a trial, the message is “Your trial includes 100 endpoints. Add a payment method and upgrade in the Outpost portal to add more.”
A downloaded installer is not checked when you download it. A computer that
runs it after the limit is reached is refused when it tries to enroll, and the
agent log shows the same message followed by Endpoints already enrolled keep working.
Resolution
Section titled “Resolution”- Upgrade your plan. See Upgrade or change your plan.
- Or retire endpoints you no longer manage. A retired endpoint stops counting. See Retire or uninstall the agent.
Endpoints that are already enrolled keep working either way.
Cause: the Windows installer refused to install
Section titled “Cause: the Windows installer refused to install”How to confirm it
Section titled “How to confirm it”The installer shows one of these messages, and writes it to its log:
| Message | Cause | Fix |
|---|---|---|
| This installer has no configuration and cannot enroll this computer. | The file is not one downloaded from the console, or it was changed after download. | Download a new installer from Enroll a device. |
| Outpost Setup needs administrator rights and did not get them. | It was not run elevated. | Right-click the installer and select Run as administrator. |
| agent.json was not found next to this installer. | The MSI was run without agent.json beside it. | Extract the whole .zip and run the MSI from that folder. |
Resolution
Section titled “Resolution”Fix the cause in the table and run the installer again.
Cause: the endpoint cannot reach your Outpost
Section titled “Cause: the endpoint cannot reach your Outpost”An endpoint that stops reporting appears in the Gone quiet view under Endpoints > All endpoints. By default, an alert is raised when an endpoint is unseen for 30 minutes. A computer that is turned off or asleep appears there too, and needs nothing.
How to confirm it
Section titled “How to confirm it”On the computer, the tray app’s Device Info view, or the agent log, shows why the connection failed:
| Message | Usual cause |
|---|---|
| DNS lookup failed: the server name could not be resolved | The computer’s DNS cannot resolve your Outpost’s address. |
| Connection refused: the server is not accepting connections | Something between the computer and the internet is rejecting the connection. |
| Host unreachable: no network route to the server | The computer has no route to the internet. |
| Connection timed out: the server did not respond | A firewall is dropping outbound traffic on port 443, or a required proxy is not configured. |
| Secure connection failed: certificate or TLS error | A proxy or firewall is inspecting TLS traffic, or the endpoint was retired and its certificate revoked. |
| Connection reset by the server or a network device | A network device is closing the connection. |
Resolution
Section titled “Resolution”- Allow outbound TCP port 443 from the computer to your Outpost.
- If the computer needs a proxy, configure it. See Proxies.
- Exempt your Outpost from TLS inspection. The agent trusts only your Outpost’s own certificate authority and authenticates with its own certificate, so a proxy that decrypts and re-signs the traffic breaks the connection.
- If the endpoint was retired, it cannot reconnect. Enroll it again. See Retire or uninstall the agent.
Cause: the endpoint enrolled but never reported in
Section titled “Cause: the endpoint enrolled but never reported in”The endpoint appears in the Never reported in view: it enrolled, but no inventory has arrived.
How to confirm it
Section titled “How to confirm it”Check the agent service and the log on the computer, as in Check first.
Resolution
Section titled “Resolution”Start the service if it is stopped. If the log shows connection errors, follow the endpoint cannot reach your Outpost.
Still stuck
Section titled “Still stuck”Collect these before you contact support:
- The agent version. Run
outpost-agent versionon the computer. - The operating system and its version.
- The exact message, copied from the console, the installer, or the log.
- The last 100 lines of the agent log.
- What changed most recently: a new firewall rule, proxy, or image.
Then see Support.
Content is licensed CC BY 4.0. Code samples are MIT. Outpost and the Outpost mark are trademarks of Outpost Business Solutions, PBC and are not covered by either license.