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 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 and remove agent manually

  3. In new workspace, perform server registration 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.

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 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 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 (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 (shown under the Manual policy), or from the CLI with alpacon agent upgrade SERVER, 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 if an upgrade is already running, or 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. 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 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.
  • 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.

Last updated: