---
title: "Connection issues"
description: "Diagnose failed connections during a work session. Check the server, account, session scope, and network, then use the matching recovery step to reconnect."
---

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

# 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](/use/servers/monitor/#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](/learn/security/network/))
3. If the server reaches Alpacon through a proxy, set the proxy for the agent's service (see [Proxy support](/learn/security/network/#proxy-support))
4. After fixing network or firewall, wait for agent to reconnect; if not, [restart the agent](/use/servers/register/#troubleshooting) or [CLI agent restart](/reference/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](/use/servers/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](/use/servers/register/) for more commands
4. For agent-specific problems, see [Agent issues](/use/servers/troubleshooting/)

**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](https://status.alpacax.com) for an ongoing platform incident
2. If you need to reach the server before the incident is resolved, use the [emergency access you kept](/learn/faq/#what-happens-if-alpacon-goes-down): a [restricted SSH account](/use/servers/configure-network/#transitioning-from-ssh-to-alpacon) or your cloud provider's console. If External access detection is on and the server is [covered](/use/audit/governance/external-access/coverage/), these direct logins are recorded and appear in [External access](/use/audit/governance/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](/use/work-sessions/). 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](#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](/use/work-sessions/detail/#launch-features-in-the-browser)

**Terminal closes during a Websh session**

The terminal's closure message identifies the cause. See [Why a session ended](/use/work-sessions/terminal/sessions/#why-a-session-ended) for each outcome and what to do, and [Limits](/use/work-sessions/terminal/sessions/#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](/reference/error-messages/#server_not_commissioned).

**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](/use/servers/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](/reference/error-messages/#server_not_connected).

**What to do:**

- Refer to [When server status shows Disconnected](#when-server-status-shows-disconnected) above to diagnose and resolve the connection issue
- After the server shows **Connected**, retry the Websh connection

### 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](/reference/error-messages/#workspace_direct_root_disabled).

**What to do:**

- Ask a workspace admin to turn on **Direct root login** in [Access rules](/use/policies/server-access/)
- 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](/reference/error-messages/#server_username_groupname_invalid).

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](/use/work-sessions/account-selection/#who-can-use-an-account-other-than-their-own): 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](/reference/error-messages/#system_uid_conflict).

**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](/use/iam/users/resolve-conflicts/)
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](/reference/error-messages/#system_user_access_denied).

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

Source: https://docs.alpacax.com/use/work-sessions/troubleshoot-connections/