cli/cli · error

error getting tunnel client: %w

Error message

error getting tunnel client: %w

What it means

Thrown by NewCodespaceConnection when getTunnelClient fails, i.e. tunnelManager.CreateTunnel / the tunnel-client creation step (via the microsoft/dev-tunnels SDK) errors while setting up the SSH-based tunnel client for the codespace. This talks to the dev-tunnels service using the Connect/ManagePorts access tokens from the codespace's TunnelProperties.

Source

Thrown at internal/codespaces/connection/connection.go:75

	managementToken := tunnelProperties.ManagePortsAccessToken

	// Create the tunnel definition
	tunnel := &tunnels.Tunnel{
		AccessTokens: map[tunnels.TunnelAccessScope]string{tunnels.TunnelAccessScopeConnect: connectToken, tunnels.TunnelAccessScopeManagePorts: managementToken},
		TunnelID:     tunnelProperties.TunnelId,
		ClusterID:    tunnelProperties.ClusterId,
		Domain:       tunnelProperties.Domain,
	}

	// Create options
	options := &tunnels.TunnelRequestOptions{
		IncludePorts: true,
	}

	// Create the tunnel client (not connected yet)
	tunnelClient, err := getTunnelClient(ctx, tunnelManager, tunnel, options)
	if err != nil {
		return nil, fmt.Errorf("error getting tunnel client: %w", err)
	}

	return &CodespaceConnection{
		tunnelProperties:           tunnelProperties,
		TunnelManager:              tunnelManager,
		TunnelClient:               tunnelClient,
		Options:                    options,
		Tunnel:                     tunnel,
		AllowedPortPrivacySettings: allowedPortPrivacySettings,
	}, nil
}

// Connect connects the client to the tunnel.
func (c *CodespaceConnection) Connect(ctx context.Context) error {
	// Lock the mutex to prevent race conditions with the underlying SSH connection
	c.TunnelClient.mu.Lock()
	defer c.TunnelClient.mu.Unlock()

View on GitHub (pinned to 0eeec0b92e)

Solutions

1. Stop and restart the codespace (gh codespace stop then connect again) to mint fresh tunnel tokens.
2. Retry after a dev-tunnels service incident; check status indicators for GitHub Codespaces.
3. Ensure the network allows traffic to the tunnel service host in TunnelProperties.ServiceUri (often *.tunnels.api.visualstudio.com or regional equivalents).
4. If tokens are persistently invalid, delete and recreate the codespace.

conn, err := connection.NewCodespaceConnection(ctx, cs, httpClient)
if err != nil && strings.Contains(err.Error(), "error getting tunnel client") {
    // tunnel tokens may be stale: stop/start the codespace, then retry once
    _ = apiClient.StopCodespace(ctx, cs.Name)
    time.Sleep(10 * time.Second)
    conn, err = connection.NewCodespaceConnection(ctx, cs, httpClient)
}

When it happens

Trigger: Connecting to a codespace where the tunnel service rejects the request: expired/invalid tunnel access tokens, tunnel not found on the cluster (tunnel already torn down), dev-tunnels service outage, or network failure reaching the tunnel service URI.

Common situations: Long-lived codespace records whose tunnel tokens expired; codespace shut down/deleted concurrently; dev-tunnels service incidents; restrictive networks blocking the tunnel endpoints (non-GitHub hosts, which is why the credential-free ExternalHTTPClient is used).

Related errors

• error searching repositories: %w
• error getting codespace: %w
• error getting tunnel management client: %w
• error connecting to tunnel: %w
• failed to build tcp address: %w

AI-assisted analysis of cli/cli@0eeec0b92e (2026-08-15). Data as JSON: /api/errors/6f38e12b19a56551. Report an issue: GitHub.