cloudflare/cloudflared · error

%s is not a valid virtual network ID

Error message

%s is not a valid virtual network ID

What it means

VnetFilter.NewFromCLI parses the --id flag as a UUID when listing virtual networks. If uuid.Parse fails, the raw string is wrapped as "<value> is not a valid virtual network ID". It is pure client-side input validation: the value was never sent to the API.

Source

Thrown at cfapi/virtual_network_filter.go:79

	f.queryParams.Set("is_deleted", strconv.FormatBool(isDeleted))
}

func (f *VnetFilter) MaxFetchSize(max uint) {
	f.queryParams.Set("per_page", strconv.Itoa(int(max)))
}

func (f VnetFilter) Encode() string {
	return f.queryParams.Encode()
}

// NewFromCLI parses CLI flags to discover which filters should get applied to list virtual networks.
func NewFromCLI(c *cli.Context) (*VnetFilter, error) {
	f := NewVnetFilter()

	if id := c.String("id"); id != "" {
		vnetId, err := uuid.Parse(id)
		if err != nil {
			return nil, errors.Wrapf(err, "%s is not a valid virtual network ID", id)
		}
		f.ById(vnetId)
	}

	if name := c.String("name"); name != "" {
		f.ByName(name)
	}

	if c.IsSet("is-default") {
		f.ByDefaultStatus(c.Bool("is-default"))
	}

	f.WithDeleted(c.Bool("show-deleted"))

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

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Get the exact vnet UUID from `cloudflared tunnel vnet list` (or the dashboard) and pass that to --id.
2. If you only know the name, use --name <name> instead of --id.
3. Strip braces/whitespace and ensure the ID is a 36-character hyphenated UUID.
4. In scripts, validate with uuid.Parse before invoking the command.

Example fix

// before
cloudflared tunnel vnet list --id my-vnet
// after
cloudflared tunnel vnet list --name my-vnet
# or
cloudflared tunnel vnet list --id f85e0780-9e67-4e0e-a90d-6b2e1a5f9c11

if _, err := uuid.Parse(vnetID); err != nil {
	return fmt.Errorf("%s is not a valid UUID; use --name for names", vnetID)
}

filter, err := cfapi.NewFromCLI(c)
if err != nil {
	return cli.Exit(fmt.Sprintf("invalid filter: %v", err), 1)
}

When it happens

Trigger: Running `cloudflared tunnel vnet list --id <value>` where <value> is not a canonical RFC-4122 UUID (e.g., a vnet name passed to --id, truncated ID, or curly-braced UUID).

Common situations: Copy-pasting a name or partial ID from the dashboard into --id; scripting that passes $VNET_NAME instead of $VNET_ID; Windows-style {GUID} formatting.

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
• %w: %v
• unabled to parse 'connector-id' flag into a valid UUID: %w
• Couldn't parse UUID from %s
• %s is not a valid tunnel ID

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