cloudflare/cloudflared · error

%s is not a valid client ID (must be a UUID)

Error message

%s is not a valid client ID (must be a UUID)

What it means

cloudflared validates the --connector-id flag with uuid.Parse before issuing a cleanup-connections request. If the value is not a syntactically valid UUID the command aborts with this wrapped parse error. It is a pure client-side input validation failure; no API call is made.

Source

Thrown at cmd/cloudflared/tunnel/subcommand_context.go:295

func (sc *subcommandContext) runWithCredentials(credentials connection.Credentials) error {
	sc.log.Info().Str(LogFieldTunnelID, credentials.TunnelID.String()).Msg("Starting tunnel")

	return StartServer(
		sc.c,
		buildInfo,
		&connection.TunnelProperties{Credentials: credentials},
		sc.log,
	)
}

func (sc *subcommandContext) cleanupConnections(tunnelIDs []uuid.UUID) error {
	params := cfapi.NewCleanupParams()
	extraLog := ""
	if connector := sc.c.String("connector-id"); connector != "" {
		connectorID, err := uuid.Parse(connector)
		if err != nil {
			return errors.Wrapf(err, "%s is not a valid client ID (must be a UUID)", connector)
		}
		params.ForClient(connectorID)
		extraLog = fmt.Sprintf(" for connector-id %s", connectorID.String())
	}

	client, err := sc.client()
	if err != nil {
		return err
	}
	for _, tunnelID := range tunnelIDs {
		sc.log.Info().Msgf("Cleanup connection for tunnel %s%s", tunnelID, extraLog)
		if err := client.CleanupConnections(tunnelID, params); err != nil {
			sc.log.Error().Msgf("Error cleaning up connections for tunnel %v, error :%v", tunnelID, err)
		}
	}
	return nil
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Get the exact connector UUID from `cloudflared tunnel info <tunnel-id>` output and pass it verbatim
2. Quote the flag value to prevent shell mangling: --connector-id="<uuid>"
3. Check for typos/truncation — a UUID is 36 chars, 8-4-4-4-12 hex digits
4. Omit --connector-id entirely if you want to clean up connections for all connectors

Example fix

// before
cloudflared tunnel cleanup 6ff42ae2-765d-4adf-8112-afc330cba951 --connector-id my-laptop
// after
cloudflared tunnel cleanup 6ff42ae2-765d-4adf-8112-afc330cba951 --connector-id 1e3b1f6a-8f2c-4d09-9e88-3fa2b7c9d4a1

func validUUID(s string) bool {
    _, err := uuid.Parse(strings.TrimSpace(s))
    return err == nil
}
if !validUUID(connectorID) { return errors.New("--connector-id must be a UUID") }

func isUUIDString(s string) bool {
    var id uuid.UUID
    return uuid.Parse(s, &id) == nil // or: uuid.Validate(s) == nil
}

connectorID, err := uuid.Parse(flagValue)
if err != nil {
    return fmt.Errorf("--connector-id %q is not a valid UUID: %w", flagValue, err)
}

When it happens

Trigger: `cloudflared tunnel cleanup <tunnel-id> --connector-id <value>` where <value> is not a valid UUID string (typo, truncated ID, bare connector name, extra whitespace).

Common situations: Copying a connector ID from logs with surrounding text; passing a connector *name* instead of its UUID; hand-typing the UUID and dropping characters; shell interpolation expanding to empty string.

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

• ErrInvalidTunnelID
• Invalid CIDR supplied for %s
• unable to generate a connector UUID: %w
• invalid connection override: %s
• %w: %v

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