--- title: "Troubleshoot the agent" description: "Fix an endpoint that does not enroll, an installer that refuses to run, a plan endpoint limit, or an endpoint that has gone offline, and find the agent's logs." url: "https://support.outpostplatform.com/agent/troubleshooting/" product: "agent" type: "troubleshooting" status: "draft" ai_summary: "Troubleshooting the Outpost agent. Log locations per OS. Enrollment refused (expired or used token, wrong client), plan endpoint limit message, Windows installer refusals (no configuration, no admin rights, MSI without agent.json), endpoints offline (DNS, refused, timeout, TLS inspection, proxy, retired certificate), and what to collect before contacting support." source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/agent/troubleshooting.md" license: "CC BY 4.0" --- # 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 1. Check that the agent service is running. **On Windows:** ```powershell Get-Service OutpostAgent, OutpostWatchdog ``` **On 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`. 2. Read the last lines of the agent's log. Most failures name their cause there. See [Where the logs are](#logs). 3. 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 {#logs} | 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 {#enrollment} 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 The agent log repeats a line like this: ```text enrollment REJECTED - the bootstrap token is invalid, expired, or for another client; generate a fresh installer if this persists ``` A 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 1. Download a new installer, or a [staged rollout](/agent/deploy-at-scale/#staged-rollout) installer for many computers, from **Enroll a device**, choosing the right site. 2. Run it on the computer. On a computer where the agent is already installed, you can instead apply the new `agent.json` with `outpost-agent import-config`, or enroll with a token. See [Deploy the agent at scale](/agent/deploy-at-scale/#token-only). ## Cause: the plan's endpoint limit is reached {#plan-limit} 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](/account/plans-and-limits/). ### 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: ```text 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 - Upgrade your plan. See [Upgrade or change your plan](/account/change-plan/). - Or retire endpoints you no longer manage. A retired endpoint stops counting. See [Retire or uninstall the agent](/agent/retire-and-uninstall/). Endpoints that are already enrolled keep working either way. ## Cause: the Windows installer refused to install {#installer} ### 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 Fix the cause in the table and run the installer again. ## Cause: the endpoint cannot reach your Outpost {#offline} 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 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 - Allow outbound TCP port 443 from the computer to your Outpost. - If the computer needs a proxy, configure it. See [Proxies](/agent/deploy-at-scale/#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](/agent/retire-and-uninstall/#bring-a-computer-back). ## Cause: the endpoint enrolled but never reported in {#never-reported} The endpoint appears in the **Never reported in** view: it enrolled, but no inventory has arrived. ### How to confirm it Check the agent service and the log on the computer, as in [Check first](#check-first). ### Resolution Start the service if it is stopped. If the log shows connection errors, follow [the endpoint cannot reach your Outpost](#offline). ## Still stuck Collect these before you contact support: - The agent version. Run `outpost-agent version` on 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](/support/).