caddyserver/caddy · error

unflagged argument \"%s\" is overridden by flags

Error message

unflagged argument \"%s\" is overridden by flags

What it means

'caddy respond' rejects the invocation when a positional argument is supplied together with both an explicit --status flag and a non-empty --body flag, since the argument would be silently ignored. The %q shows the redundant argument. This guards against ambiguity where the user believes their argument took effect.

Source

Thrown at modules/caddyhttp/staticresp.go:342

	debug := fl.Bool("debug")
	arg := fl.Arg(0)

	if fl.NArg() > 1 {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("too many unflagged arguments")
	}

	// prefer status and body from explicit flags
	statusCode, body := statusCodeFl, bodyFl

	// figure out if status code was explicitly specified; this lets
	// us set a non-zero value as the default but is a little hacky
	statusCodeFlagSpecified := slices.Contains(os.Args, "--status")

	// try to determine what kind of parameter the unnamed argument is
	if arg != "" {
		// specifying body and status flags makes the argument redundant/unused
		if bodyFl != "" && statusCodeFlagSpecified {
			return caddy.ExitCodeFailedStartup, fmt.Errorf("unflagged argument \"%s\" is overridden by flags", arg)
		}

		// if a valid 3-digit number, treat as status code; otherwise body
		if argInt, err := strconv.Atoi(arg); err == nil && !statusCodeFlagSpecified {
			if argInt >= 100 && argInt <= 999 {
				statusCode = argInt
			}
		} else if body == "" {
			body = arg
		}
	}

	// if we still need a body, see if stdin is being piped
	if body == "" {
		stdinInfo, err := os.Stdin.Stat()
		if err != nil {
			return caddy.ExitCodeFailedStartup, err
		}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Remove the redundant positional argument
2. Or drop --status/--body flags and let the argument carry the value
3. Audit scripts that call 'caddy respond' for duplicated value sources

Example fix

# before
caddy respond "hi" --status 404 --body "bye"

# after
caddy respond --status 404 --body "bye"

if positionalArg != "" && bodyFlag != "" && statusFlagSet {
    return errors.New("remove the redundant positional argument or the --status/--body flags")
}

When it happens

Trigger: caddy respond "hi" --status 404 --body "bye" — positional "hi" plus both flags set; statusCodeFlagSpecified is true and bodyFl non-empty.

Common situations: Scripts evolved over time where an old positional argument was left alongside newly added flags; refactoring command invocations.

Related errors

• too many unflagged arguments
• invalid header flag: %v
• parsing environment file: %v
• setting environment variables: %v
• unable to enumerate installed plugins: %v

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