cloudflare/cloudflared · error · ErrInvalidTunnelID

%w: %v

Error message

%w: %v

What it means

GetManagementToken validates the tunnel ID passed as a CLI argument before requesting a management token. When uuid.Parse fails, the raw error is wrapped with ErrInvalidTunnelID via fmt.Errorf("%w: %v", ErrInvalidTunnelID, err), producing an error chain whose message renders literally as '%w: %v: <parse error>'. It signals the user supplied a string that is not a valid RFC-4122 UUID.

Source

Thrown at cmd/cloudflared/cliutil/management.go:51

	var apiURL string
	if userCreds.IsFEDEndpoint() {
		apiURL = credentials.FedRampBaseApiURL
	} else {
		apiURL = c.String(cfdflags.ApiURL)
	}

	client, err := userCreds.Client(apiURL, buildInfo.UserAgent(), log)
	if err != nil {
		return "", err
	}

	tunnelIDString := c.Args().First()
	if tunnelIDString == "" {
		return "", ErrNoTunnelID
	}
	tunnelID, err := uuid.Parse(tunnelIDString)
	if err != nil {
		return "", fmt.Errorf("%w: %v", ErrInvalidTunnelID, err)
	}

	token, err := client.GetManagementToken(tunnelID, res)
	if err != nil {
		return "", err
	}

	return token, nil
}

// CreateStderrLogger creates a logger that outputs to stderr to avoid interfering with stdout
func CreateStderrLogger(c *cli.Context) *zerolog.Logger {
	level, levelErr := zerolog.ParseLevel(c.String(cfdflags.LogLevel))
	if levelErr != nil {
		level = zerolog.InfoLevel
	}
	var writer io.Writer
	switch c.String(cfdflags.LogFormatOutput) {

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Run `cloudflared tunnel list` and copy the full UUID as the argument instead of a tunnel name
2. Validate the ID with github.com/google/uuid.Parse before invoking the command
3. Trim whitespace and strip surrounding quotes/braces from the argument
4. Upgrade or downgrade cloudflared to a version where tunnel-name lookup for the token command is supported, if relying on names

Example fix

// before
cloudflared tunnel token my-tunnel
// after
cloudflared tunnel token 570d3f16-e26a-4e1b-bde1-3c9e4b0a1f2b

import "github.com/google/uuid"

if id := c.Args().First(); uuid.Validate(id) != nil {
    return fmt.Errorf("tunnel ID must be a UUID, got %q; run 'cloudflared tunnel list'", id)
}

func isValidTunnelID(s string) bool {
    _, err := uuid.Parse(strings.TrimSpace(s))
    return err == nil
}

When it happens

Trigger: Calling GetManagementToken (via tokenCommand, managementTokenCommand, or buildURL) with c.Args().First() that is empty-adjacent garbage: a truncated UUID, a tunnel name instead of an ID, extra whitespace, or a UUID with wrong formatting (braces, no hyphens variant mismatch with uuid.Parse).

Common situations: Users paste a tunnel name or partial ID from the dashboard; scripts pass shell variables that were never set; users on older cloudflared versions where tunnel names were accepted for `cloudflared tunnel token`.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• ErrInvalidTunnelID
• unabled to parse 'connector-id' flag into a valid UUID: %w
• Couldn't parse UUID from %s
• %s is not a valid virtual network ID
• %s is not a valid tunnel ID

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