---
title: "Agent issues"
description: "Troubleshoot an Alpamon agent that will not install, connect, or upgrade. Check service status, logs, and platform permissions before trying recovery steps."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Agent issues

Troubleshooting guide for Alpamon agent issues.

## Agent installation failure

**Incorrect OS family selection**

Selecting the wrong OS family for your server during agent installation can cause installation to fail.

The installation command Alpacon generates depends on the OS family you select, so selecting the wrong one causes installation to fail. This applies to the generated command and to manual installation alike.

**What to do:**

1. Verify the server's actual OS family:

   - **Debian family**: Ubuntu, Debian, etc.
   - **Red Hat family**: RHEL, CentOS, Fedora, Amazon/Rocky/Oracle Linux, etc.
   - **SUSE family**: openSUSE, SLES
   - **macOS**: macOS 11 or later
   - **Windows**: Windows Server 2019 / 2022 / 2025, Windows 10 1803+, Windows 11

2. When registering the server on the [Register a server](/use/servers/register/) page, select the correct OS family. On openSUSE or SLES, choose **SUSE family**: the Red Hat family command fails there.

3. If using a manual installation script, install the agent using a script that matches the selected OS family:

   - Debian family: script that includes `apt-get install -y alpamon`
   - Red Hat family: script that includes `yum install -y alpamon`
   - SUSE family: script that includes `zypper --non-interactive install alpamon`
   - macOS: script that includes `brew install alpamon`
   - Windows: PowerShell script that runs `alpamon.exe register`

4. If the server was registered with the wrong OS family, delete the server and register it again with the correct OS family

**Workspace migration**

If you register a server from another workspace to a new workspace without removing the agent first, the agent may continue to be connected to the old workspace. In this case, server connection is not possible in the new workspace.

**What to do:**

1. In old workspace, delete server with **automatic agent removal** enabled (removes previously installed agent from server)

2. If cannot access old workspace, refer to [Remove server](/use/servers/remove/) and remove agent manually

3. In new workspace, perform [server registration](/use/servers/register/) and agent installation from scratch

## Re-registration and recovery

These commands recover a host whose registration is stuck or half-finished. Run them on the server itself (local console, RDP, or cloud serial console), not over Websh, and on **alpamon v2.3.0 or later**. Older agents do not have `register --force` or `unregister` (plain `alpamon register` still exists)—uninstall the agent manually and delete the server from the **Servers** page, then register again.

**`alpamon register` stops with `config file already exists`**

The host is already registered, so `alpamon register` refuses to register again. Re-register in one step with `alpamon register --force`, which registers anew and retires the previous registration once the new one succeeds. You can also run `alpamon unregister` first and then `alpamon register`.

**Registration failed partway through**

If a registration attempt fails after it has already created some state, the host can be left half-registered. Run `alpamon register --force` to register cleanly and retire the leftover registration.

**Preserving state for diagnosis**

By default a failed `alpamon register` rolls back the state it created during that run. To keep that partial state for troubleshooting, add `--no-rollback` (for example, `alpamon register --force --no-rollback`). This is for debugging only and leaves partial state behind.

## Windows agent issues

**Service won't start**

If the `alpamon` Windows Service fails to start, inspect the service state and the agent log first.

```powershell
sc.exe query alpamon
Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 100
```

For Service Control Manager errors that don't appear in the agent log (for example, the binary is missing or unreadable), open **Event Viewer** and check **Windows Logs** → **System** for entries from `Service Control Manager`, plus **Applications and Services Logs** for any `alpamon` entries.

**Access denied during `alpamon register` or service operations**

Both `alpamon register` and the service control commands (`sc.exe`, `Restart-Service`) require Administrator privileges. Re-run from an elevated PowerShell (Run as Administrator). `alpamon register` surfaces an elevation hint when it cannot copy the binary to `C:\Program Files\alpamon\`.

If you see `ERROR_SHARING_VIOLATION` while reinstalling, the existing `alpamon.exe` is held open by the running service. Stop it first and retry:

```powershell
sc.exe stop alpamon
.\alpamon.exe register --url https://your-workspace.us1.alpacon.io --token YOUR_REGISTRATION_TOKEN
```

If the registration itself is stuck or half-finished, see [Re-registration and recovery](#re-registration-and-recovery).

**Websh fails with `PowerShell error 8009001d`**

This was a TLS-related Websh handshake error on early Windows builds and has been fixed in newer Alpamon releases. [Upgrade the agent](/use/servers/register/install/#upgrading-the-agent) to the latest release, then retry.

**WebFTP shows more than the user's home on Windows, including `C:\Windows\System32\...`**

This is expected. On Windows, WebFTP is not confined to a single user's home directory: it can browse, read, and write any path the agent can reach on the host, including system directories such as `C:\Windows\System32`. Access is governed by your Alpacon roles and permissions and by which users are allowed to connect, not by a per-user home boundary on the server. Grant WebFTP access deliberately, and use Alpacon roles to limit who can reach sensitive locations. See [WebFTP permissions](/use/work-sessions/files/permissions/) for how access is controlled.

## macOS agent issues

**Service won't start**

Inspect the launchd service and the agent log:

```bash
sudo launchctl print system/com.alpacax.alpamon
tail -n 100 /var/log/alpamon/alpamon.log
```

For launchd-level failures (for example, the executable cannot be found or the plist is invalid), filter **Console.app** for `com.alpacax.alpamon` to see launchd's own error messages.

**Restart the service**

```bash
sudo launchctl kickstart -k system/com.alpacax.alpamon
```

**Agent can't read protected directories**

macOS requires Full Disk Access for processes that touch system-protected paths (Mail, Messages, Time Machine, parts of `~/Library`, etc.). If the agent reports permission errors when reading those locations, grant Full Disk Access to the `alpamon` binary in **System Settings** → **Privacy & Security** → **Full Disk Access**, then restart the service.

The binary location depends on your Mac:

- Apple Silicon: `/opt/homebrew/bin/alpamon`
- Intel: `/usr/local/bin/alpamon`

## Agent upgrade issues

Alpacon keeps the Alpamon agent up to date in two ways:

- **Automatic**: under the **Latest** update policy in [Agent updates](/use/workspace/settings/agent-updates/) (the default), registered agents upgrade to new releases on their own, inside the workspace's maintenance window.
- **On demand**: upgrade a specific server with **Upgrade agent** on its [Agent card](/use/servers/manage/#agent-card) (shown under the **Manual** policy), or from the CLI with [`alpacon agent upgrade SERVER`](/reference/cli/agent/upgrade/), then check progress with `alpacon exec ls`.

During an upgrade the agent fetches the new version and restarts automatically. The server may briefly show **Offline** and then reconnect. If the update can't be applied, the agent keeps running the previous version. How the update is delivered depends on the platform:

- **Linux** (Debian/Ubuntu, RHEL/CentOS, openSUSE/SLES): through the system package manager (`apt`, `yum` or `zypper`) from the Alpacon package repository.
- **macOS** and **Windows**: downloaded from GitHub Releases.

**Upgrade doesn't start**

- Check [`server_agent_upgrade_in_progress`](/reference/error-messages/#server_agent_upgrade_in_progress) if an upgrade is already running, or [`server_agent_upgrade_not_needed`](/reference/error-messages/#server_agent_upgrade_not_needed) if the agent is on the current release.
- Confirm the server shows **Online**. An offline agent can't receive the upgrade request.
- Run `alpacon agent upgrade SERVER` and check `alpacon exec ls` for the result.
- If you rely on automatic upgrades, confirm the update policy in **Agent updates** is **Latest**, not **Manual**, and check the maintenance window. Automatic upgrades start only inside it, and a window change applies from the next Monday's plan.
- Check the server's [upgrade history](/use/servers/manage/#upgrade-history). A **Refused** row means the upgrade was withdrawn before it reached the agent.

**Upgrade fails or the version doesn't change**

- **Connectivity**: every platform checks the latest version at `api.github.com`, so the server needs outbound HTTPS to `api.github.com`. On **Linux**, the upgrade then runs through `apt`, `yum` or `zypper`, so the server must also reach the Alpacon package repository, directly or through the workspace **Package proxy** setting. On SLES, the package manager also fails while the subscription is expired or inactive; check it with `SUSEConnect --status`. On **macOS** and **Windows**, the agent downloads the release directly from `github.com` and `release-assets.githubusercontent.com`.
- Check the agent log for the reason, then trigger the upgrade again:
  - Linux: `sudo journalctl -u alpamon -n 100`
  - macOS: `tail -n 100 /var/log/alpamon/alpamon.log`
  - Windows: `Get-Content "$env:ProgramData\alpamon\log\alpamon.log" -Tail 100`
- The server's [upgrade history](/use/servers/manage/#upgrade-history) shows the outcome of each attempt and, for a failed or rolled-back one, the reason. **Alpacon configuration issue; no action needed** is on Alpacon's side; nothing needs changing on your server.
- **Windows agent older than 2.4.0**: the upgrade fails with **Unsupported platform** in the upgrade history, and Alpacon doesn't schedule another one until the agent reports a different version. Replace the binary by hand once; see [upgrading the agent](/use/servers/register/install/#upgrading-the-agent).
- A failed upgrade leaves the agent running the previous version. Fix the cause (usually network or package-repository access) and retry.

**Confirm the current version**

The server detail page shows the running agent version. You can re-run the upgrade at any time; if the agent is already on the latest release, nothing changes, and **Upgrade agent** on the Agent card is disabled with the note **Agent is up to date**.

Source: https://docs.alpacax.com/use/servers/troubleshooting/
