Tunnel Closed

tunnel-closed · 410

The tunnel has ended and won't come back, so the API refused its heartbeat.

reason says what ended it, openSeconds how long it was open, and keyName the API key it was opened with, null without one. workspaceName is left out when the workspace is gone. A tunnel lives on a 90-second lease that each heartbeat renews.

Besides the members every error carries, this type adds tunnelId, reason, openSeconds, keyName and workspaceName.

Common causes

  • closed: the tunnel was closed, as with Ctrl-C.
  • connection_lost: no heartbeat came before the lease ran out. The CLI opens a fresh tunnel in its place.
  • key_revoked, member_removed or role_changed: the key or the seat it was opened with can't connect any more, and the CLI exits with code 3.
  • database_deleted or environment_deleted: the database or its environment was deleted, and the CLI exits with code 4.
  • database_stopped: the database was stopped, and the CLI exits with code 5.
  • workspace_suspended: the workspace was suspended, and the CLI exits with code 7.

How to fix the call

  • After closed or connection_lost, open a new tunnel; the CLI does it by itself for a lost one.
  • After any other reason, fix what it names before opening a new one: a new key, the seat back, or a database that runs.
  • Don't send more heartbeats to this tunnel: it stays closed.

Example response

json
{
  "type": "tunnel-closed",
  "title": "Tunnel Closed",
  "detail": "The tunnel is closed: key_revoked.",
  "tunnelId": "0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402",
  "reason": "key_revoked",
  "openSeconds": 1843,
  "keyName": "laptop",
  "workspaceName": "Acme",
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/tunnels/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402/heartbeat",
  "method": "POST",
  "instance": "POST /v1/tunnels/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402/heartbeat",
  "status": 410,
  "docs": "https://ghaym.me/docs/errors/tunnel-closed"
}