Connection issues

Troubleshooting guide for server connection issues.

When server status shows Disconnected

Server status may show Disconnected for different reasons. Check the following scenarios to resolve it yourself.

1. Server is powered off or shut down

If the server is stopped, Alpacon cannot maintain a connection.

What to do:

  1. Server power and boot status check
  2. After server is running, wait briefly for Alpamon agent to reconnect automatically
  3. If status remains Disconnected, check agent status

2. When network connection to Alpacon is broken

The Alpamon agent connects to Alpacon over outbound HTTPS/WSS. If the server’s network blocks this or the network is down, status will show Disconnected.

What to do:

  1. Server outbound internet access check (e.g. curl -I https://alpacon.io or workspace endpoint)
  2. Firewall or proxy outbound HTTPS (443) and WSS allowance check (see Network requirements)
  3. If using a proxy, set HTTP_PROXY and HTTPS_PROXY on the server
  4. After fixing network or firewall, wait for agent to reconnect; if not, restart the agent or CLI agent restart

3. Agent not installed or not running

If the agent is not installed, was removed, or the agent process is not running, the server will show Disconnected.

What to do:

  1. On the server, verify Alpamon agent is installed and running (e.g. systemctl status alpamon on Linux)
  2. If not installed, install using installation script or instructions from Server connect
  3. If installed but not running, start or restart the agent (e.g. systemctl start alpamon or systemctl restart alpamon on Linux). See Server register for more commands
  4. For agent-specific problems, see Agent issues

When unable to connect to Websh

Console button is not available

Websh access is only available when the server is Connected to Alpacon. The Console button for Websh access is displayed only for connected servers.

What to do:

Terminal closes during a Websh session

The terminal may close unexpectedly while you are using Websh. Alpacon provides workspace admins with a remote session termination feature. A Staff or higher admin can terminate a user’s active Websh session at their discretion when they deem it necessary for security—in that case, the user’s terminal is closed.

What to do:

  • Check if workspace admin remotely terminated the session
  • If server is still Connected, start a new Websh session from server list or Websh page

When Websh session fails to start

When you attempt to open a Websh session and see an error message, the cause depends on the server state or your account configuration. Below are the common scenarios and how to resolve them.

Server is not yet commissioned

The server has been registered in Alpacon but the initial setup has not been completed.

What to do:

  1. Go to the server detail page and check if the server status shows Not commissioned
  2. Complete the server installation steps—see Server connect for instructions
  3. Once the server is commissioned, retry the Websh connection

Server is not connected

The server was previously connected but is currently offline or unreachable.

What to do:

Direct root access is disabled

You attempted to connect as the root user, but the workspace security policy does not allow direct root access.

What to do:

  • Ask a workspace admin to enable Allow direct root access in workspace access control settings
  • Alternatively, connect with your own account and use sudo to run privileged commands

Account does not exist or you do not have permission

You are trying to connect with a username or group that is not registered on the server, or you do not have permission to use it.

This can happen when:

  • Your account has not been provisioned on the server yet
  • You are trying to use another user’s account without proper access
  • The group you belong to is not assigned to this server

What to do:

  1. Go to the server detail page and check the Access tab to verify your account is listed
  2. If your account is not listed, ask a workspace admin to assign the appropriate group to the server or provision your account
  3. If you are trying to use a system account, verify that you have sudo privilege—only Staff, Superuser, or group Manager/Owner can access system accounts

System user UID conflict

Your Alpacon account has a UID that conflicts with an existing system user on the server. This prevents Alpacon from safely provisioning your account.

What to do:

  1. Go to the server detail page > Access tab and look for accounts marked with a Conflict tag
  2. To resolve the conflict, a workspace admin needs to either:
    • Change the conflicting system user’s UID on the server
    • Adjust your Alpacon account’s UID in IAM user settings
  3. After the conflict is resolved, retry the Websh connection

System user login is disabled or account has expired

Your account exists on the server but login access has been disabled, or the account has passed its expiration date.

What to do:

  1. Check with a workspace admin or server administrator whether the system user account has been disabled or expired on the server
  2. On the server itself, verify the account status:
    • Login shell is set to a valid shell (not /usr/sbin/nologin or /bin/false)
    • Account expiration date has not passed (check with chage -l <username>)
  3. After the account is re-enabled or expiration is updated, retry the Websh connection