---
title: "Tunnel troubleshooting"
description: "Resolve Alpacon tunnel failures by matching CLI messages and server error codes. Check sign-in, server settings, port choices, and the work session lifetime."
---

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

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

To find the server toggle, see [server settings](/use/servers/manage/#tunnel-and-code-editor). For session refusals, see [work-session gate errors](/reference/cli/work-session/#gate-errors).

Source: https://docs.alpacax.com/use/work-sessions/tunnels/troubleshooting/