cloudflare/cloudflared · error

you cannot use UUIDs as tunnel names

Error message

you cannot use UUIDs as tunnel names

What it means

CreateTunnel rejects names that parse as valid UUIDs, returning this client-side validation error. This prevents ambiguity/collisions with tunnel IDs, which are themselves UUIDs. The check happens locally before any API call via uuid.Parse(name).

Source

Thrown at cfapi/tunnel.go:97

	return &CleanupParams{
		queryParams: url.Values{},
	}
}

func (cp *CleanupParams) ForClient(clientID uuid.UUID) {
	cp.queryParams.Set("client_id", clientID.String())
}

func (cp CleanupParams) encode() string {
	return cp.queryParams.Encode()
}

func (r *RESTClient) CreateTunnel(name string, tunnelSecret []byte) (*TunnelWithToken, error) {
	if name == "" {
		return nil, errors.New("tunnel name required")
	}
	if _, err := uuid.Parse(name); err == nil {
		return nil, errors.New("you cannot use UUIDs as tunnel names")
	}
	body := &newTunnel{
		Name:         name,
		TunnelSecret: tunnelSecret,
	}

	resp, err := r.sendRequest("POST", r.baseEndpoints.accountLevel, body)
	if err != nil {
		return nil, errors.Wrap(err, "REST request failed")
	}
	defer resp.Body.Close()

	switch resp.StatusCode {
	case http.StatusOK:
		var tunnel TunnelWithToken
		if serdeErr := parseResponse(resp.Body, &tunnel); serdeErr != nil {
			return nil, serdeErr
		}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Use a human-readable name that is not a UUID (prefix it, e.g. "tunnel-<uuid>")
2. Pass the tunnel ID to lookup APIs, not CreateTunnel
3. Sanitize generated names before calling CreateTunnel

Example fix

// before
name := uuid.NewString()
tunnel, err := client.CreateTunnel(name, secret)
// after
name := "tunnel-" + uuid.NewString()
tunnel, err := client.CreateTunnel(name, secret)

if _, err := uuid.Parse(name); err == nil {
    return errors.New("tunnel name must not be a UUID; prefix it, e.g. 'tunnel-<uuid>'")
}

t, err := client.CreateTunnel(name, secret)
if err != nil && strings.Contains(err.Error(), "UUIDs as tunnel names") {
    return fmt.Errorf("rename tunnel: %w", err)
}

When it happens

Trigger: Calling RESTClient.CreateTunnel with a name like "123e4567-e89b-12d3-a456-426614174000" that uuid.Parse accepts — e.g. using a UUID generator to name tunnels.

Common situations: Scripts auto-generating tunnel names with uuidgen or similar; accidentally passing a tunnel ID where a name is expected; templating bugs substituting the ID variable into the name field.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• tunnel name required
• ErrInvalidTunnelID
• ErrTunnelNameConflict
• Decoded tunnel secret must be at least 32 bytes long
• API errors: %s

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