What causes "unabled to parse 'connector-id' flag into a valid UUID: %w" in cloudflare/cloudflared?

Use the connector's UUID (RFC 4122 format, e.g. 123e4567-e89b-12d3-a456-426614174000)

unabled to parse 'connector-id' flag into a valid UUID: %w

Error message

unabled to parse 'connector-id' flag into a valid UUID: %w

What it means

Raised in buildURL for `cloudflared tail` when the --connector-id flag is non-empty but cannot be parsed by uuid.Parse. The management URL can only be built with a well-formed connector UUID, so the tail command stops before connecting to the management websocket.

Source

Thrown at cmd/cloudflared/tail/cmd.go:237

	claims, err := management.ParseToken(token)
	if err != nil {
		return url.URL{}, fmt.Errorf("failed to determine if token is FED: %w", err)
	}

	var managementHostname string
	if claims.IsFed() {
		managementHostname = credentials.FedRampHostname
	} else {
		managementHostname = c.String(cfdflags.ManagementHostname)
	}

	query := url.Values{}
	query.Add("access_token", token)
	connector := c.String("connector-id")
	if connector != "" {
		connectorID, err := uuid.Parse(connector)
		if err != nil {
			return url.URL{}, fmt.Errorf("unabled to parse 'connector-id' flag into a valid UUID: %w", err)
		}
		query.Add("connector_id", connectorID.String())
	}
	return url.URL{Scheme: "wss", Host: managementHostname, Path: "/logs", RawQuery: query.Encode()}, nil
}

func printLine(log *management.Log, logger *zerolog.Logger) {
	fields, err := json.Marshal(log.Fields)
	if err != nil {
		fields = []byte("unable to parse fields")
		logger.Debug().Msgf("unable to parse fields from event %+v", log)
	}
	fmt.Printf("%s %s %s %s %s\n", log.Time, log.Level, log.Event, log.Message, fields)
}

func printJSON(log *management.Log, logger *zerolog.Logger) {
	output, err := json.Marshal(log)
	if err != nil {

View on GitHub (pinned to 2253eeeb25)

Solutions

Use the connector's UUID (RFC 4122 format, e.g. 123e4567-e89b-12d3-a456-426614174000)
Find the connector ID in the Cloudflare Zero Trust dashboard or via the API
Omit --connector-id if you want logs from all connectors
Normalize the UUID (add dashes) if you have a 32-hex-character string

Example fix

# before
cloudflared tail --connector-id my-tunnel-connector <tunnel-id>
# after
cloudflared tail --connector-id 123e4567-e89b-12d3-a456-426614174000 <tunnel-id>

Defensive patterns

Strategy: validation

Validate before calling

if id := os.Args[flagIdx+1]; id != "" {
	if _, err := uuid.Parse(id); err != nil {
		return fmt.Errorf("--connector-id must be a UUID")
	}
}

Type guard

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

Try / catch

if _, err := uuid.Parse(connectorFlag); err != nil {
	return fmt.Errorf("--connector-id must be a UUID, got %q", connectorFlag)
}

Prevention

Copy connector UUIDs from the Zero Trust dashboard exactly
Insert dashes into 32-char hex strings before use
Drop the flag entirely to tail all connectors

When it happens

Trigger: Running `cloudflared tail --connector-id my-connector <tunnel-id>` — any value that is not a canonical or accepted UUID format (e.g. missing dashes, extra characters, empty braces).

Common situations: Passing a connector name instead of its UUID, copying a connector ID truncated or with surrounding text from the dashboard URL.

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

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