cloudflare/cloudflared · error

ErrInvalidTunnelID

ErrInvalidTunnelID

Error message

unable to parse provided tunnel id as a valid UUID

What it means

GetManagementToken parses the supplied tunnel ID with github.com/google/uuid. If the argument is present but not a valid RFC-4122 UUID string, the parse error is wrapped with the sentinel ErrInvalidTunnelID so callers can errors.Is() it. This catches typos and wrong identifiers before hitting the Cloudflare API.

Source

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

	"fmt"
	"io"
	"os"
	"time"

	"github.com/google/uuid"
	"github.com/mattn/go-colorable"
	"github.com/rs/zerolog"
	"github.com/urfave/cli/v2"

	"github.com/cloudflare/cloudflared/cfapi"
	cfdflags "github.com/cloudflare/cloudflared/cmd/cloudflared/flags"
	"github.com/cloudflare/cloudflared/credentials"
)

// Error definitions for management token operations
var (
	ErrNoTunnelID      = errors.New("no tunnel ID provided")
	ErrInvalidTunnelID = errors.New("unable to parse provided tunnel id as a valid UUID")
)

// GetManagementToken acquires a management token from Cloudflare API for the specified resource
func GetManagementToken(c *cli.Context, log *zerolog.Logger, res cfapi.ManagementResource, buildInfo *BuildInfo) (string, error) {
	userCreds, err := credentials.Read(c.String(cfdflags.OriginCert), log)
	if err != nil {
		return "", err
	}

	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 {

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Run `cloudflared tunnel list` and copy the full UUID (8-4-4-4-12 hex with dashes).
2. Use `cloudflared tunnel info <uuid>` with the exact UUID, not the tunnel name.
3. If scripting, validate the format first: UUID regex `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`.

Example fix

// before
if !uuid.IsValid(tunnelID) { ... } // no pre-check, cloudflared fails
cloudflared tunnel info "my-tunnel"
// after
cloudflared tunnel list | grep my-tunnel   # get UUID e.g. 6ff42ae2-765d-4adf-8112-... 
cloudflared tunnel info 6ff42ae2-765d-4adf-8112-5f4c8c564c11

import "github.com/google/uuid"
func isUUID(s string) bool { _, err := uuid.Parse(s); return err == nil }

if _, err := cliutil.GetManagementToken(c, log, res, buildInfo); err != nil {
    if errors.Is(err, cliutil.ErrInvalidTunnelID) {
        return fmt.Errorf("pass the tunnel UUID from `cloudflared tunnel list`, not its name")
    }
    return err
}

When it happens

Trigger: `cloudflared tunnel info my-tunnel-name` (name instead of UUID), a truncated or mistyped UUID, or passing the connection/hostname ID where the tunnel UUID is expected.

Common situations: Users passing the human-readable tunnel name from the dashboard instead of its UUID; copying a partial ID from logs; shell truncation of the argument.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• you cannot use UUIDs as tunnel names
• %w: %v
• 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

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