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 default installation script works regardless of OS type, so installation usually succeeds. However, when installing the agent manually, the installation script differs by OS family, so selecting the wrong OS will cause installation to fail.

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.
    • 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

  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
    • 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

Windows agent issues

Service won’t start

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

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:

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

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 to the latest Alpamon (alpamon upgrade or re-run the installer) and retry.

WebFTP can’t read C:\Windows\System32\... or other paths outside the user’s home

This is by design. On Windows, WebFTP limits browsing to the user’s home directory and does not expose system paths. Place files you want to transfer under the user’s home directory, or use Websh for read-only inspection of system locations.

macOS agent issues

Service won’t start

Inspect the launchd service and the agent log:

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

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

Content needs to be written

Last updated: