invalid --sample value provided, please make sure it is in t

Error message

invalid --sample value provided, please make sure it is in the range (0.0 .. 1.0)

What it means

Range-validation error in parseFilters for `cloudflared tail`. It fires when the --sample flag is <= 0.0 or > 1.0; the sampling rate must be a fraction in (0.0 .. 1.0] so the CLI rejects the value before sending StreamingFilters to the edge.

Source

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

	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 {
		// When no filters are provided, do not return a StreamingFilters struct
		return nil, nil
	}

	return &management.StreamingFilters{
		Level:    level,
		Events:   events,
		Sampling: sample,
	}, nil
}

// buildURL will build the management url to contain the required query parameters to authenticate the request.
func buildURL(c *cli.Context, log *zerolog.Logger, res cfapi.ManagementResource) (url.URL, error) {
	var err error

View on GitHub (pinned to 2253eeeb25)

Solutions

Use a decimal fraction between 0 and 1, e.g. 0.5 for 50%
Use 1.0 to receive all events
Omit --sample entirely for default (unfiltered) behavior

Example fix

# before
cloudflared tail --sample 50 <tunnel-id>
# after
cloudflared tail --sample 0.5 <tunnel-id>

Defensive patterns

Strategy: validation

Validate before calling

s, err := strconv.ParseFloat(sampleFlag, 64)
if err != nil || s <= 0.0 || s > 1.0 {
	return fmt.Errorf("--sample must be in (0.0 .. 1.0]")
}

Type guard

func validSample(f float64) bool { return f > 0.0 && f <= 1.0 }

Prevention

Convert percentages to fractions before passing (50% -> 0.5)
Omit --sample for full-stream default behavior
Clamp computed sample rates into (0,1] before use

When it happens

Trigger: Running e.g. `cloudflared tail --sample 1.5 <tunnel-id>` or `--sample 0 <tunnel-id>` — any value <= 0.0 or > 1.0.

Common situations: Passing a percentage (50 instead of 0.5), a negative number, or intending 'all events' with a wrong representation of 1.0.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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