caddyserver/caddy · error

reading envfile flag: %v

Error message

reading envfile flag: %v

What it means

Returned by the `caddy start` command when reading the --envfile flag's string slice fails. This is a command-line parsing error from the flag layer, not a file I/O error — the flag value itself could not be interpreted as a string slice. Practically it signals a malformed repeated flag or a flag-definition mismatch.

Source

Thrown at cmd/commandfuncs.go:56

	"github.com/caddyserver/caddy/v2"
	"github.com/caddyserver/caddy/v2/caddyconfig"
	"github.com/caddyserver/caddy/v2/caddyconfig/caddyfile"
	"github.com/caddyserver/caddy/v2/internal"
)

func cmdStart(fl Flags) (int, error) {
	configFlag := fl.String("config")
	configAdapterFlag := fl.String("adapter")
	pidfileFlag := fl.String("pidfile")
	watchFlag := fl.Bool("watch")

	var err error
	var envfileFlag []string
	envfileFlag, err = fl.GetStringSlice("envfile")
	if err != nil {
		return caddy.ExitCodeFailedStartup,
			fmt.Errorf("reading envfile flag: %v", err)
	}

	// open a listener to which the child process will connect when
	// it is ready to confirm that it has successfully started
	ln, err := listenTCPForPingback(net.Listen)
	if err != nil {
		return caddy.ExitCodeFailedStartup,
			fmt.Errorf("opening listener for success confirmation: %v", err)
	}
	defer ln.Close()

	// craft the command with a pingback address and with a
	// pipe for its stdin, so we can tell it our confirmation
	// code that we expect so that some random port scan at
	// the most unfortunate time won't fool us into thinking
	// the child succeeded (i.e. the alternative is to just
	// wait for any connection on our listener, but better to
	// ensure it's the process we're expecting - we can be

View on GitHub (pinned to 50e54ee279)

Solutions

1. Run caddy start --envfile ./env once with simple quoting to isolate the flag
2. Print help (caddy start --help) and confirm the flag spelling and expected format
3. Drop --envfile and export the variables directly if the flag keeps failing

Example fix

# before
caddy start --envfile
# after
caddy start --envfile ./.env

exitCode, err := cmdStart(fl)
if err != nil && strings.Contains(err.Error(), "reading envfile flag") {
    // flag-layer failure: correct the --envfile arguments and re-invoke
    log.Fatal("check --envfile spelling/value; run: caddy start --help")
}

When it happens

Trigger: Passing --envfile in a form the flag parser cannot coerce to a slice; invoking caddy start through a wrapper that mangles flag arguments; version mismatch where the running binary's flag set differs from the invoked one.

Common situations: Shell scripts quoting flags incorrectly; aliases or wrappers appending stray arguments; extremely rare in normal use.

Related errors

• opening listener for success confirmation: %v
• creating stdin pipe: %v
• generating random confirmation bytes: %v
• starting caddy process: %v
• caddy process exited with error: %v

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