cloudflare/cloudflared · error

--metrics has to be provided

Error message

--metrics has to be provided

What it means

readyCommand polls the /ready endpoint on the metrics server, so it needs the metrics address. If the --metrics flag was not explicitly set, cloudflared refuses to guess the address and returns "--metrics has to be provided".

Source

Thrown at cmd/cloudflared/tunnel/subcommands.go:484

	return strings.Join(output, ", ")
}

func buildReadyCommand() *cli.Command {
	return &cli.Command{
		Name:               "ready",
		Action:             cliutil.ConfiguredAction(readyCommand),
		Usage:              "Call /ready endpoint and return proper exit code",
		UsageText:          "cloudflared tunnel [tunnel command options] ready [subcommand options]",
		Description:        "cloudflared tunnel ready will return proper exit code based on the /ready endpoint",
		Flags:              []cli.Flag{},
		CustomHelpTemplate: commandHelpTemplate(),
	}
}

func readyCommand(c *cli.Context) error {
	metricsOpts := c.String(flags.Metrics)
	if !c.IsSet(flags.Metrics) {
		return errors.New("--metrics has to be provided")
	}

	requestURL := fmt.Sprintf("http://%s/ready", metricsOpts)
	req, err := http.NewRequest(http.MethodGet, requestURL, nil)
	if err != nil {
		return err
	}
	// nolint: gosec // URL is constructed from the user-configured local metrics endpoint.
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer func() { _ = res.Body.Close() }()
	if res.StatusCode != 200 {
		body, err := io.ReadAll(res.Body)
		if err != nil {
			return err
		}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Run `cloudflared tunnel ready --metrics 127.0.0.1:PORT` matching your metrics listener address.
2. Ensure the metrics server is running on that address (check the running cloudflared's metrics flag).
3. Update health-check scripts/monitoring to include --metrics.

Example fix

// before
cloudflared tunnel ready
// after
cloudflared tunnel ready --metrics 127.0.0.1:20241

if ! grep -q -- '--metrics' <<<"$CMD"; then set -- "$@" --metrics 127.0.0.1:20241; fi
cloudflared tunnel ready "$@"

When it happens

Trigger: Running `cloudflared tunnel ready` without --metrics (e.g. `cloudflared tunnel ready` alone), relying on a config-file value which is not counted as "set" on the CLI.

Common situations: Health-check scripts omitting --metrics; assuming the metrics default from the config file satisfies the flag check; copy-pasting the command from docs without the flag.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• tunnelCmdErrorMessage
• Did not receive final destination from client. The --destina
• http://%s/ready endpoint returned status code %d %s
• Error opening metrics server listener
• the argument path must be a directory

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