cloudflare/cloudflared · error

namedTunnel is nil

Error message

namedTunnel is nil

What it means

StartServer requires a resolved named-tunnel configuration to proceed; if `namedTunnel` is nil the process cannot build edge connections or credentials. This is an internal invariant check guarding against StartServer being invoked without tunnel credentials (e.g. token path failed to produce NamedTunnelConfig).

Source

Thrown at cmd/cloudflared/tunnel/cmd.go:397

	go waitForSignal(graceShutdownC, log)

	connectedSignal := signal.New(make(chan struct{}))
	go notifySystemd(connectedSignal)
	if c.IsSet("pidfile") {
		go writePidFile(connectedSignal, c.String("pidfile"), log)
	}

	wg.Add(1)
	go func() {
		defer wg.Done()
		autoupdater := updater.NewAutoUpdater(
			c.Bool(cfdflags.NoAutoUpdate), c.Duration(cfdflags.AutoUpdateFreq), &listeners, log,
		)
		errC <- autoupdater.Run(ctx)
	}()

	if namedTunnel == nil {
		return fmt.Errorf("namedTunnel is nil")
	}

	logTransport := logger.CreateTransportLoggerFromContext(c, logger.EnableTerminalLog)

	observer := connection.NewObserver(log, logTransport)

	// Send Quick Tunnel URL to UI if applicable
	quickTunnelURL := namedTunnel.QuickTunnelUrl
	if quickTunnelURL != "" {
		observer.SendURL(quickTunnelURL)
	}

	tunnelConfig, orchestratorConfig, err := prepareTunnelConfig(ctx, c, info, log, logTransport, observer, namedTunnel)
	if err != nil {
		log.Err(err).Msg("Couldn't start tunnel")
		return err
	}
	connectorID := tunnelConfig.ClientConfig.ConnectorID

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Ensure the tunnel is started with credentials: pass `--token <token>` (or TUNNEL_TOKEN env) or a valid credentials file/TunnelID so namedTunnel is populated.
2. Verify the credentials file exists and parses (check `credentials-file` path and file contents).
3. If embedding, construct and pass a valid *supervisor.NamedTunnelConfig to StartServer instead of nil.

Example fix

// before
_ = exec.Command("cloudflared", "tunnel", "run").Run()
// after
_ = exec.Command("cloudflared", "tunnel", "run", "--token", os.Getenv("TUNNEL_TOKEN")).Run()

// shell: verify credentials are resolvable before starting
[ -n "$TUNNEL_TOKEN" ] || [ -f /etc/cloudflared/credentials.json ] || { echo "no tunnel credentials"; exit 1; }

When it happens

Trigger: Calling StartServer (directly from RunQuickTunnel or runWithCredentials paths) with a cli.Context whose named tunnel config was never populated — e.g. no `--token`, no credentials file, and no TunnelID in config, yet the run path was forced.

Common situations: Custom integrations or scripts calling cloudflared's StartServer programmatically; or a regression in flag/config parsing where TUNNEL_TOKEN was not forwarded (empty env var, mistyped secret key in orchestrator).

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• ErrTunnelNameConflict
• tunnel name required
• you cannot use UUIDs as tunnel names
• ErrNoTunnelID
• ErrInvalidTunnelID

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/7414b5a5d09e62b5. Report an issue: GitHub.