Troubleshooting

Find the message you see in your browser or terminal below. Most problems come from the local service, the client or the state of your account.

Quick checks

1. Is your local service running? On the computer that runs the client: curl -I http://127.0.0.1:3000 (use your port).
2. Is the client connected? portlark connect prints Handshake OK and the tunnel's public URL. Agents can run portlark agent status --id <tunnel-id> --json and look for "state": "connected".
3. Do the ports match? The local address of the tunnel in the dashboard must match the port your service listens on.
4. Is your access active? Check Dashboard → Plans and billing.
5. Are you using the exact URL shown in the dashboard, including https://?

"This tunnel is offline"

No client is connected for this tunnel. Start it with portlark connect (or portlark agent up --id <tunnel-id> --json) and keep it running. If the client exits immediately, read its error message and look it up on this page.

502 Bad Gateway, or the page never loads

The client is connected, but it cannot get a response from your local service.

• Local service not running. Start it and check it with curl on the client's computer.
• Port mismatch. For example, the tunnel forwards to 127.0.0.1:3000 but your dev server runs on 5173. Start the service on the configured port, or create a new tunnel with the correct address.
• Wrong interface. If the service listens only on an IPv6 address or another network interface, make it listen on 127.0.0.1 as well.
• Service on another machine. It must listen on the network interface (not only localhost), and its firewall must allow the client's computer.
• HTTPS-only local service. HTTP tunnels forward plain HTTP. Point the tunnel at the service's HTTP port.

For Agent-managed tunnels, "local_reachable": false in agent status means the client cannot open a connection to the local address.

"Invalid Host header" or "This host is not allowed"

Your development server rejects the tunnel hostname. Allow .tunnel.portlark.com in its allowed-hosts setting. See HTTP and HTTPS tunnels.

handshake 401 / "invalid client token"

The saved token was revoked or deleted. Run portlark setup to sign in again and create a new token. For Agent credentials, run portlark agent login --new --json and approve the request again.

handshake 403 / "token is not authorized for this tunnel"

The token cannot connect this tunnel. Common causes:

• The tunnel was deleted. Run portlark setup and select a current tunnel.
• An Agent credential is limited to the tunnel you approved. Approve a new request for the other tunnel.
• Your trial or subscription has ended, or the account is suspended. See below.

"tunnel is not owned or its lease is not runnable"

The tunnel exists but cannot run right now, usually because your access has ended or the tunnel was suspended after a plan change. Check Plans and billing, then reconnect.

"Your access has expired. Choose a plan or contact support."

Your 30-day trial or your paid period has ended. Choose a plan in Dashboard → Plans and billing. Recreating a tunnel does not restart a trial. See Plans and billing.

"tunnel_quota_exceeded" when creating a tunnel

You have reached your plan's tunnel limit. The free trial includes one tunnel. Delete an unused tunnel, or choose a plan with more tunnels on https://portlark.com/pricing.

"TCP access requires approval"

TCP tunnels are available only after approval. See Approved TCP access.

"This account is suspended"

Contact support@portlark.com from your account address.

no config found; run "portlark setup" first

There is no saved configuration on this computer, for example after portlark logout. Run portlark setup.

Sign-in fails in portlark setup

Use your PortLark account email and password, not a client token. Verify your email address before signing in. Forgot your password? Reset it at https://portlark.com/forgot-password.

Emails do not arrive

Check your spam folder and that the address is correct. Verification links are valid for 24 hours; password reset codes are valid for 15 minutes, and you can request a new one after a minute. Never send your password or reset code to anyone, including support.

Slow responses

All traffic is relayed through PortLark servers in New York, so latency depends on the distance between you, your visitors and New York. The most common bottleneck is the upload speed of the network your computer is on.

Contact support

Email support@portlark.com with:

• your operating system and client version (portlark --version),
• the tunnel ID,
• the time of the problem, including your time zone,
• the exact error message.

Remove tokens and other credentials from logs before sending them. To report abuse of a PortLark URL, contact abuse@portlark.com.