cloudflare/cloudflared · error

%s is not a valid tunnel ID

Error message

%s is not a valid tunnel ID

What it means

`cloudflared tunnel list --id <value>` parses the --id flag with uuid.Parse to filter the list to one tunnel. If the value is not a well-formed UUID (8-4-4-4-12 hex format), the parse error is wrapped as '<value> is not a valid tunnel ID'.

Source

Thrown at cmd/cloudflared/tunnel/subcommands.go:366

	if !c.Bool("show-deleted") {
		filter.NoDeleted()
	}
	if name := c.String(flags.Name); name != "" {
		filter.ByName(name)
	}
	if namePrefix := c.String("name-prefix"); namePrefix != "" {
		filter.ByNamePrefix(namePrefix)
	}
	if excludePrefix := c.String("exclude-name-prefix"); excludePrefix != "" {
		filter.ExcludeNameWithPrefix(excludePrefix)
	}
	if existedAt := c.Timestamp("time"); existedAt != nil {
		filter.ByExistedAt(*existedAt)
	}
	if id := c.String("id"); id != "" {
		tunnelID, err := uuid.Parse(id)
		if err != nil {
			return errors.Wrapf(err, "%s is not a valid tunnel ID", id)
		}
		filter.ByTunnelID(tunnelID)
	}
	if maxFetch := c.Int("max-fetch-size"); maxFetch > 0 {
		filter.MaxFetchSize(uint(maxFetch))
	}

	tunnels, err := sc.list(filter)
	if err != nil {
		return err
	}

	// Sort the tunnels
	sortBy := c.String("sort-by")
	invalidSortField := false
	sort.Slice(tunnels, func(i, j int) bool {
		cmp := func() bool {
			switch sortBy {

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Get the exact UUID via `cloudflared tunnel list` and pass it to --id
2. Verify the ID is a valid UUID v4-like string (8-4-4-4-12 hex chars)
3. If you only know the name, run list without --id and filter by name instead
4. Trim whitespace/quotes around the value in shell scripts

Example fix

// before
cloudflared tunnel list --id my-tunnel
// after
cloudflared tunnel list --id 7c5b3a20-1b2f-4a3e-9c8d-1234567890ab

func isValidUUID(s string) bool {
	_, err := uuid.Parse(strings.TrimSpace(s))
	return err == nil
}
// before calling: cloudflared tunnel list --id <v>
if !isValidUUID(flagValue) { /* fix input before invoking */ }

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

tunnelID, err := uuid.Parse(id)
if err != nil {
	return fmt.Errorf("%s is not a valid tunnel ID: %w", id, err)
}

When it happens

Trigger: Passing a tunnel NAME or a malformed string to the --id flag of `cloudflared tunnel list` instead of a UUID — e.g. --id my-tunnel or --id with stray whitespace/quotes.

Common situations: Copy-pasting the tunnel name instead of its UUID from `cloudflared tunnel list` output; extra shell quoting or trailing whitespace in scripts; truncated UUIDs from earlier command output.

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.

Related errors

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

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