Tunnel troubleshooting
Check that your work session is active, covers the server, and includes port forwarding. Tokens cannot open a tunnel; use alpacon login without -t.
CLI messages
In the messages below, <v> is the supplied port and … is the operating system or connection detail.
| Message | Meaning and action |
|---|---|
a token cannot open a tunnel; run 'alpacon login' without -t (on a machine without a browser, open the printed URL on another device) and try again | Sign in without -t, attach an active session, and try again |
invalid remote port: port must be between 1 and 65535 | Set -r to a port in that range |
invalid local port: port "<v>" is not a number | Use a numeric local port, or -l 0 to choose a free one |
failed to listen on local port: … | Check the detail; if the port is occupied, choose another or use -l 0 |
failed to establish tunnel connection: … | Check the detail and the server’s connection before retrying |
Error: tunnel connection lost: session closed by remote | Check whether the work session completed, expired, or was revoked. Reconnect under an active session |
Warning: Tunnel closed: session closed by remote | A tunnel running with -- COMMAND closed and interrupted the local command. Check that command’s result before retrying |
Server error codes
The CLI can show a server refusal as request failed (code: X) within its tunnel-creation error. Match X below. Quoted text is the corresponding console error message; the last two rows apply to code editor sessions.
| Code | Meaning | What to do |
|---|---|---|
tunnel_not_enabled# | "Tunneling isn't enabled for this server." The server's tunnel setting is off. | Ask an administrator to enable tunnels for the server. |
tunnel_requirements_not_met# | "Tunnel requires agent version 2.0.0 or higher. Please upgrade the agent first." Appears when enabling tunnels on an unsupported agent. | Ask an administrator to upgrade Alpamon, then enable tunnels. |
tunnel_invalid_port# | "The port must be between 1 and 65535." | Use a port from 1 to 65535 for -r. |
tunnel_multiple_clients_not_allowed# | "Only one client is allowed per tunnel." | Open a separate tunnel for each client. |
tunnel_multiple_agents_not_allowed# | "Only one agent is allowed per tunnel." | Open a separate tunnel. |
tunnel_session_closed# | "This session is already closed. Please open the code editor again." Appears when reconnecting to a closed editor session. | Open the code editor again from the work session. |
tunnel_not_editor# | "This action is only available for code editor sessions." | Use the action only on a code editor session. |
To find the server toggle, see server settings. For session refusals, see work-session gate errors.