invalid --level filter provided, please use one of the follo

Error message

invalid --level filter provided, please use one of the following Log Levels: debug, info, warn, error

What it means

Validation error in parseFilters while building streaming filters for `cloudflared tail`. It fires when the --level flag value does not match one of the recognized log levels (debug, info, warn, error) per management.ParseLogLevel, so the CLI refuses to start the stream with an invalid filter.

Source

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

		log.Error().Msgf("management request failed validation: (%d) %s", e.Code, e.Message)
	}
}

// parseFilters will attempt to parse provided filters to send to with the EventStartStreaming
func parseFilters(c *cli.Context) (*management.StreamingFilters, error) {
	var level *management.LogLevel
	var sample float64

	events := make([]management.LogEventType, 0)

	argLevel := c.String("level")
	argEvents := c.StringSlice("event")
	argSample := c.Float64("sample")

	if argLevel != "" {
		l, ok := management.ParseLogLevel(argLevel)
		if !ok {
			return nil, fmt.Errorf("invalid --level filter provided, please use one of the following Log Levels: debug, info, warn, error")
		}
		level = &l
	}

	for _, v := range argEvents {
		t, ok := management.ParseLogEventType(v)
		if !ok {
			return nil, fmt.Errorf("invalid --event filter provided, please use one of the following EventTypes: cloudflared, http, tcp, udp")
		}
		events = append(events, t)
	}

	if argSample <= 0.0 || argSample > 1.0 {
		return nil, fmt.Errorf("invalid --sample value provided, please make sure it is in the range (0.0 .. 1.0)")
	}
	sample = argSample

	if level == nil && len(events) == 0 && argSample != 1.0 {

View on GitHub (pinned to 2253eeeb25)

Solutions

Use one of the documented levels: debug, info, warn, error
Run `cloudflared tail --help` to see accepted --level values
Check case/formatting — the value must exactly match a supported level

Example fix

# before
cloudflared tail --level fatal <tunnel-id>
# after
cloudflared tail --level error <tunnel-id>

Defensive patterns

Strategy: validation

Validate before calling

var validLevels = map[string]bool{"debug": true, "info": true, "warn": true, "error": true}
if !validLevels[strings.ToLower(level)] {
	return fmt.Errorf("--level must be one of debug, info, warn, error")
}

Try / catch

if _, ok := management.ParseLogLevel(level); !ok {
	return usageError("invalid --level; expected debug|info|warn|error")
}

Prevention

Copy flag values from `cloudflared tail --help`
Remember only four levels are supported — no trace/fatal
Validate flags in scripts before invoking cloudflared

When it happens

Trigger: Running e.g. `cloudflared tail --level verbose <tunnel-id>` — any --level string not parseable as a supported level (debug, info, warn, error, and their case variants accepted by ParseLogLevel).

Common situations: Typo in the level name, copy-pasting a level from another tool (e.g. 'trace', 'fatal', 'verbose'), or using a numeric level.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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