caddyserver/caddy · error

checking if default Caddyfile exists

Error message

checking if default Caddyfile exists: %v

What it means

While looking for a default adjacent Caddyfile, os.Stat returned an error other than fs.ErrNotExist (e.g. permission denied on a parent directory). The existence check itself is what failed, so Caddy aborts instead of silently ignoring the default file.

Solutions

1. Check directory permissions along the path to the Caddyfile
2. Run the CLI from a directory you can read/stat
3. Pass --config explicitly to bypass default-file discovery

Example fix

# before
caddy run   # stat ./Caddyfile fails with EACCES

# after
chmod +rx ~/workdir && caddy run --config /etc/caddy/Caddyfile

# Ensure the working directory is traversable before running caddy:
test -r ./Caddyfile || true   # any stat error other than missing will surface here first

When it happens

Trigger: Running the CLI in a directory where a path component of ./Caddyfile cannot be traversed due to permissions, or an exotic filesystem returning an unexpected stat error.

Common situations: Homedir with restrictive permissions when running as a different user; containers with read-only or oddly mounted workdirs; rarely, race where the file disappears between stat calls returning something other than NotExist.

Related errors

• backing up current binary
• reading default Caddyfile
• download succeeded, but unable to clean up backup binary
• loading trusted root CA's PEM file
• making folder for CA database

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/efc7796515dc9d10. Report an issue: GitHub.

Appendix: source

Thrown at cmd/commandfuncs.go:923

// configFileWithRespectToDefault returns the filename to use for loading the config, based
// on whether a config file is already specified and a supported default config file exists.
func configFileWithRespectToDefault(logger *zap.Logger, configFile string) (string, error) {
	const defaultCaddyfile = "Caddyfile"

	// if no input file was specified, try a default Caddyfile if the Caddyfile adapter is plugged in
	if configFile == "" && caddyconfig.GetAdapter("caddyfile") != nil {
		_, err := os.Stat(defaultCaddyfile)
		if err == nil {
			// default Caddyfile exists
			if logger != nil {
				logger.Info("using adjacent Caddyfile")
			}
			return defaultCaddyfile, nil
		}
		if !errors.Is(err, fs.ErrNotExist) {
			// problem checking
			return configFile, fmt.Errorf("checking if default Caddyfile exists: %v", err)
		}
	}

	// default config file does not exist or is irrelevant
	return configFile, nil
}

type moduleInfo struct {
	caddyModuleID string
	goModule      *debug.Module
	err           error
}

View on GitHub (pinned to 50e54ee279)