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. The offline alert appears after about 5 minutes unless the downtime is one you started through Alpacon or the server’s alert is turned off—see Offline alert.

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 the server reaches Alpacon through a proxy, set the proxy for the agent’s service (see Proxy support)
  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 (systemctl status alpamon on Linux, sc.exe query alpamon on Windows)
  2. If not installed, install using installation script or instructions from Server connect
  3. If installed but not running, start or restart the agent (systemctl start alpamon / systemctl restart alpamon on Linux, Restart-Service alpamon on Windows). See Server register for more commands
  4. For agent-specific problems, see Agent issues

4. Platform incident

During an Alpacon platform incident, a server can show Disconnected while it keeps running. The agent reconnects on its own once the incident is resolved.

What to do:

  1. Check Alpacon status for an ongoing platform incident
  2. If you need to reach the server before the incident is resolved, use the emergency access you kept: a restricted SSH account or your cloud provider’s console. If External access detection is on and the server is covered, these direct logins are recorded and appear in External access for review, including ones made while the server was disconnected, which Alpamon 2.8.2 or later delivers once it reconnects

When unable to connect to Websh

Connect button is not available

Websh opens from a work session. A server’s Connect button, which starts a session request for that server, works only when the server is commissioned and Connected to Alpacon.

What to do:

  • Check server status by referring to When server status shows Disconnected above
  • When server status changes to Connected, click Connect and request a session with the web terminal. Once the session is active, open its Session tab and click Terminal on that server. See Use a session

Terminal closes during a Websh session

The terminal’s closure message identifies the cause. See Why a session ended for each outcome and what to do, and Limits for how session duration is counted.

What to do:

  • Read the closure message and follow the matching recovery step.
  • If the work session is active and the server is Connected, open the session’s Session tab and click Terminal on that server again. Otherwise, request another session.

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.

See the server_not_commissioned error.

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.

See the server_not_connected error.

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.

See the workspace_direct_root_disabled error.

What to do:

  • Ask a workspace admin to turn on Direct root login in Access rules
  • 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.

See the server_username_groupname_invalid error.

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 an account other than your own, verify that you can use it: only Staff, Superuser, a group Manager/Owner, or the server’s maintainer can

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.

See the system_uid_conflict error.

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.

See the system_user_access_denied error.

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
Last updated: