cloudflared tunnel rule expects a single argument, the URL t

Error message

cloudflared tunnel rule expects a single argument, the URL to test

What it means

testURLCommand requires exactly one argument: the URL to test against ingress rules. `c.Args().First()` returning empty string means the user invoked `cloudflared tunnel rule` without a URL, so cloudflared throws this error before parsing.

Source

Thrown at cmd/cloudflared/tunnel/ingress_subcommands.go:123

	if c.IsSet(ingressDataJSONFlagName) {
		ingressJSON := c.String(ingressDataJSONFlagName)
		fmt.Println("Validating rules from cmdline flag --json")
		err := json.Unmarshal([]byte(ingressJSON), &conf)
		return conf, err
	}
	conf = config.GetConfiguration()
	if conf.Source() == "" {
		return nil, errors.New("No configuration file was found. Please create one, or use the --config flag to specify its filepath. You can use the help command to learn more about configuration files")
	}
	fmt.Println("Validating rules from", conf.Source())
	return conf, nil
}

// testURLCommand checks which ingress rule matches the given URL.
func testURLCommand(c *cli.Context) error {
	requestArg := c.Args().First()
	if requestArg == "" {
		return errors.New("cloudflared tunnel rule expects a single argument, the URL to test")
	}

	requestURL, err := url.Parse(requestArg)
	if err != nil {
		return fmt.Errorf("%s is not a valid URL", requestArg)
	}
	if requestURL.Hostname() == "" && requestURL.Scheme == "" {
		return fmt.Errorf("%s doesn't have a hostname, consider adding a scheme", requestArg)
	}

	conf := config.GetConfiguration()
	fmt.Println("Using rules from", conf.Source())
	ing, err := ingress.ParseIngress(conf)
	if err != nil {
		return errors.Wrap(err, "Validation failed")
	}

	_, i := ing.FindMatchingRule(requestURL.Hostname(), requestURL.Path)

View on GitHub (pinned to 2253eeeb25)

Solutions

Supply the URL to test: `cloudflared tunnel rule https://example.com/path`.
Quote URLs containing special shell characters: `cloudflared tunnel rule 'https://example.com:8080/path?q=1'`.
Check `cloudflared tunnel rule --help` for expected usage.

Example fix

// before
cloudflared tunnel rule
// after
cloudflared tunnel rule https://example.com/

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$1" ]; then echo "usage: cloudflared tunnel rule <url>" >&2; exit 1; fi

Prevention

Always pass exactly one URL argument to `tunnel rule`.
Quote URLs with special characters.
Wrap rule checks in helper scripts that assert argument presence.

When it happens

Trigger: Running `cloudflared tunnel rule` with no argument, or with only flags (e.g. `--config ...`) and no positional URL.

Common situations: Copy-pasting the command from docs but omitting the URL argument; forgetting to quote URLs so the shell splits them.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

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