cloudflare/cloudflared · error

Tag parse failure

Error message

Tag parse failure

What it means

Raised when NewTagSliceFromCLI cannot parse the values passed with the repeated --tag flag. Tags must be KEY=VALUE pairs attached to the connector; a malformed entry fails tunnel configuration. The error is logged as 'Tag parse failure' and wrapped before returning.

Source

Thrown at cmd/cloudflared/tunnel/configuration.go:138

) (*supervisor.TunnelConfig, *orchestration.Config, error) {
	transportProtocol := c.String(flags.Protocol)
	isPostQuantumEnforced := c.Bool(flags.PostQuantum)
	featureSelector, err := features.NewFeatureSelector(ctx, namedTunnel.Credentials.AccountTag, c.StringSlice(flags.Features), isPostQuantumEnforced, log)
	if err != nil {
		return nil, nil, errors.Wrap(err, "Failed to create feature selector")
	}

	clientConfig, err := client.NewConfig(info.Version(), info.OSArch(), featureSelector)
	if err != nil {
		return nil, nil, err
	}

	log.Info().Msgf("Generated Connector ID: %s", clientConfig.ConnectorID)

	tags, err := NewTagSliceFromCLI(c.StringSlice(flags.Tag))
	if err != nil {
		log.Err(err).Msg("Tag parse failure")
		return nil, nil, errors.Wrap(err, "Tag parse failure")
	}
	tags = append(tags, pogs.Tag{Name: "ID", Value: clientConfig.ConnectorID.String()})

	cfg := config.GetConfiguration()
	ingressRules, err := ingress.ParseIngressFromConfigAndCLI(cfg, c, log)
	if err != nil {
		return nil, nil, err
	}

	protocolSelector, err := connection.NewProtocolSelector(transportProtocol, log)
	if err != nil {
		return nil, nil, err
	}
	log.Info().Msgf("Initial protocol %s", protocolSelector.Current())

	edgeTLSConfigs := make(map[connection.Protocol]*tls.Config, len(connection.ProtocolList))
	for _, p := range connection.ProtocolList {
		tlsSettings := p.TLSSettings()

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Format every --tag as KEY=VALUE, e.g. --tag team=platform.
2. Quote tags in the shell if they contain special characters: --tag "env=prod us".
3. Remove empty or malformed tag entries from config file / startup scripts.
4. Run `cloudflared tunnel run --help` to see the expected tag syntax.

Example fix

// before
cloudflared tunnel run --tag team my-tunnel
// after
cloudflared tunnel run --tag team=platform my-tunnel

func validTag(t string) bool {
	parts := strings.SplitN(t, "=", 2)
	return len(parts) == 2 && parts[0] != "" && parts[1] != ""
}
// check each --tag value with validTag before running

tags, err := NewTagSliceFromCLI(c.StringSlice(flags.Tag))
if err != nil {
	log.Err(err).Msg("Tag parse failure")
	return nil, nil, errors.Wrap(err, "Tag parse failure")
}

When it happens

Trigger: Running `cloudflared tunnel run --tag foo` (missing '=value'), `--tag =bar` (empty key), or `--tag a=b=c` style values that the parser rejects.

Common situations: Users forgetting the '=' separator; values containing unquoted '=' or spaces in shell scripts; config files with tag lists copied from docs using wrong format.

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

• No configuration file was found. Please create one, or use t
• ErrNoIngressRulesCLI
• Did not receive final destination from client. The --destina
• configuration file %s must contain entries for the tunnel to
• possible conflicting configuration in %[1]s and %[2]s. Eithe

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