cloudflare/cloudflared · error

Couldn't parse UUID from %s

Error message

Couldn't parse UUID from %s

What it means

This error is returned by NewIpRouteFilterFromCLI (cfapi/ip_route_filter.go:89) when the value supplied for the tunnel-ID filter flag is not a parseable UUID. The library parses it with github.com/google/uuid.Parse before building the IpRouteFilter; any malformed string (wrong length, non-hex characters, wrong dash placement) causes the wrapped parse error.

Source

Thrown at cfapi/ip_route_filter.go:89

		return nil, err
	} else if subset != nil {
		f.NetworkIsSupersetOf(*subset)
	}

	if superset, err := cidrFromFlag(c, filterSupersetIpRoute); err != nil {
		return nil, err
	} else if superset != nil {
		f.NetworkIsSupersetOf(*superset)
	}

	if comment := c.String(filterIpRouteComment.Name); comment != "" {
		f.CommentIs(comment)
	}

	if tunnelID := c.String(filterIpRouteTunnelID.Name); tunnelID != "" {
		u, err := uuid.Parse(tunnelID)
		if err != nil {
			return nil, errors.Wrapf(err, "Couldn't parse UUID from %s", filterIpRouteTunnelID.Name)
		}
		f.TunnelID(u)
	}

	if vnetId := c.String(filterIpRouteByVnet.Name); vnetId != "" {
		u, err := uuid.Parse(vnetId)
		if err != nil {
			return nil, errors.Wrapf(err, "Couldn't parse UUID from %s", filterIpRouteByVnet.Name)
		}
		f.VNetID(u)
	}

	if maxFetch := c.Int("max-fetch-size"); maxFetch > 0 {
		f.MaxFetchSize(uint(maxFetch))
	}

	return f, nil
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Run `cloudflared tunnel list` and copy the exact UUID from the ID column for the --tunnel-id filter value
2. Validate the value with uuid.Parse (or a regex like ^[0-9a-f]{8}-[0-9a-f]{4}-...$) before invoking the command
3. If a tunnel name is what you have, resolve it to its UUID first via the API/CLI rather than passing the name
4. Fix shell scripts that substitute empty variables into the flag (quote and check non-empty)

Example fix

// before (CLI flag value)
cloudflared tunnel route ip show --tunnel-id my-tunnel
// after
cloudflared tunnel list   # find UUID
cloudflared tunnel route ip show --tunnel-id f5df1b7e-7c99-4e12-a3f9-9d8b2c1a4e55

import "github.com/google/uuid"

func validUUID(s string) bool {
    _, err := uuid.Parse(s)
    return err == nil
}
// if !validUUID(tunnelIDFlag) { return fmt.Errorf("--tunnel-id must be a UUID, got %q", tunnelIDFlag) }

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

When it happens

Trigger: Running `cloudflared tunnel route ip show` (showRoutesCommand) with the tunnel-ID filter flag set to a value like `my-tunnel`, `1234`, or a truncated/malformed UUID string instead of a valid UUID (e.g. a name, an ID from a different resource, or a UUID with copy/paste corruption).

Common situations: Users pass the tunnel NAME instead of its ID; copy/paste drops or adds characters; scripts interpolate empty or placeholder values; confusion between tunnel ID and connection/credential IDs which have different formats.

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

• %s is not a valid tunnel ID
• 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/5d1d530a674ead1b. Report an issue: GitHub.