cloudflare/cloudflared · error

%s must be equal or less than %v

Error message

%s must be equal or less than %v

What it means

gracePeriod validates the `--grace-period` duration against connection.MaxGracePeriod (3 minutes by default); a longer value is rejected so shutdown waits stay bounded. The flag and its value come straight from the CLI/config.

Source

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

	return tunnelConfig, orchestratorConfig, nil
}

func parseConfigFlags(c *cli.Context) map[string]string {
	result := make(map[string]string)

	for _, flag := range configFlags {
		if v := c.String(flag); c.IsSet(flag) && v != "" {
			result[flag] = v
		}
	}

	return result
}

func gracePeriod(c *cli.Context) (time.Duration, error) {
	period := c.Duration(flags.GracePeriod)
	if period > connection.MaxGracePeriod {
		return time.Duration(0), fmt.Errorf("%s must be equal or less than %v", flags.GracePeriod, connection.MaxGracePeriod)
	}
	return period, nil
}

func isRunningFromTerminal() bool {
	return term.IsTerminal(int(os.Stdout.Fd())) // nolint:gosec
}

// ParseConfigIPVersion returns the IP version from possible expected values from config
func parseConfigIPVersion(version string) (v allregions.ConfigIPVersion, err error) {
	switch version {
	case "4":
		v = allregions.IPv4Only
	case "6":
		v = allregions.IPv6Only
	case "auto":
		v = allregions.Auto
	default: // unspecified or invalid

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Reduce `--grace-period` to at most the max shown in the message (e.g. 3m0s).
2. If longer drain is genuinely needed, manage connection draining at the orchestrator level (e.g. Kubernetes terminationGracePeriodSeconds) instead.
3. Remove the flag to use the default grace period.

Example fix

// before
grace-period: 10m
// after
grace-period: 3m

// shell: clamp grace-period to the 3m cap
p="${GRACE_PERIOD:-2m}"
[[ "$(echo "$p" | sed 's/[a-z]//g')" =~ ^[0-9]+$ ]] || p="2m"
cloudflared tunnel run --grace-period "$p"

When it happens

Trigger: Running `cloudflared tunnel run --grace-period 10m` or setting `grace-period: 10m` in the config file with a value above MaxGracePeriod.

Common situations: Operators wanting longer drain time during deploys set large grace periods; copied Kubernetes preStop tuning exceeds the built-in cap.

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

• 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/b8f3bc15ee4da60d. Report an issue: GitHub.