tailscale/tailscale · error

foreground listener already exists for port %d

Error message

foreground listener already exists for port %d

What it means

Raised by validateServeConfigUpdate when a background serve config wants a TCP port currently held by a foreground session. Background config cannot overwrite an active foreground listener.

Source

Thrown at ipn/ipnlocal/serve.go:1775

		return nil
	}

	// New foreground listeners must be on open ports.
	for sessionID, incomingFg := range incoming.Foreground().All() {
		if !existing.Foreground().Has(sessionID) {
			// This is a new session.
			for port := range incomingFg.TCPs() {
				if _, exists := existing.FindTCP(port); exists {
					return fmt.Errorf("listener already exists for port %d", port)
				}
			}
		}
	}

	// New background listeners cannot overwrite existing foreground listeners.
	for port := range incoming.TCP().All() {
		if _, exists := existing.FindForegroundTCP(port); exists {
			return fmt.Errorf("foreground listener already exists for port %d", port)
		}
	}

	// Incoming configuration cannot change the serve type in use by a port.
	for port, incomingHandler := range incoming.TCP().All() {
		existingHandler, exists := existing.FindTCP(port)
		if !exists {
			continue
		}

		existingServeType := serveTypeFromPortHandler(existingHandler)
		incomingServeType := serveTypeFromPortHandler(incomingHandler)
		if incomingServeType != existingServeType {
			return fmt.Errorf("want to serve %q, but port %d is already serving %q", incomingServeType, port, existingServeType)
		}
	}

	// Validations for Tailscale Services.

View on GitHub (pinned to 6e0912f979)

Solutions

1. A foreground serve listener already exists for this port; stop the running 'tailscale serve'/'tailscale funnel' foreground process (Ctrl-C) before starting another on the same port.

When it happens

Trigger: Thrown at ipn/ipnlocal/serve.go:1775 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of tailscale/tailscale@6e0912f979 (2026-08-18). Data as JSON: /api/errors/4414013f50a8b32a. Report an issue: GitHub.