No configuration file was found. Please create one, or use t

Error message

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

What it means

getConfiguration, used by ingress validation commands, requires a config file. If `--json` was not provided and config.GetConfiguration() reports an empty source, cloudflared cannot load ingress rules and throws this error. Ingress rules are only sourced from a config file or --json blob, so one must exist.

Source

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

		fmt.Println("Warning: unused keys detected in your config file. Here is a list of unused keys:")
		fmt.Println(warnings)
		return nil
	}
	fmt.Println("OK")
	return nil
}

func getConfiguration(c *cli.Context) (*config.Configuration, error) {
	var conf *config.Configuration
	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)

View on GitHub (pinned to 2253eeeb25)

Solutions

Create a configuration file at a default location (e.g. /etc/cloudflared/config.yml or ~/.cloudflared/config.yml).
Pass --config explicitly: `cloudflared tunnel --config /path/to/config.yml ingress validate`.
Alternatively validate rules from an inline blob with --json instead of a file.

Example fix

// before
cloudflared tunnel ingress validate
// after
cloudflared tunnel --config /etc/cloudflared/config.yml ingress validate

Defensive patterns

Strategy: validation

Validate before calling

if [ ! -f "$CONFIG" ]; then echo "config file $CONFIG not found" >&2; exit 1; fi
cloudflared tunnel --config "$CONFIG" ingress validate

Prevention

Always pass --config explicitly in scripts instead of relying on default search paths.
Keep the config at a standard location (/etc/cloudflared/config.yml).
Check file existence and spelling (yml vs yaml) before running ingress commands.

When it happens

Trigger: Running `cloudflared tunnel ingress validate` (or related ingress commands) with no config file at any default location and no --config/--json flag.

Common situations: Running the ingress subcommand outside a directory with config.yml; misnamed file (config.yaml vs config.yml); typo in --config path; first-time setup before creating a config.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

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