caddyserver/caddy · error

too many unflagged arguments

Error message

too many unflagged arguments

What it means

CLI argument validation for 'caddy respond': at most one positional (unflagged) argument is allowed, which may be either a status code or the body. Passing two or more positional arguments returns ExitCodeFailedStartup with this error.

Source

Thrown at modules/caddyhttp/staticresp.go:328

		server.Logs = new(ServerLogConfig)
	}

	return server, nil
}

func cmdRespond(fl caddycmd.Flags) (int, error) {
	caddy.TrapSignals()

	// get flag values
	listen := fl.String("listen")
	statusCodeFl := fl.Int("status")
	bodyFl := fl.String("body")
	accessLog := fl.Bool("access-log")
	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 {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Quote multi-word bodies: caddy respond "hello world"
2. Pass status via flag: caddy respond --status 200 "hello world"
3. Use --body and --status flags instead of positional arguments entirely

Example fix

# before
caddy respond 200 hello world

# after
caddy respond --status 200 --body "hello world"

// wrapper for scripts:
args := flag.Args()
if len(args) > 1 {
    return fmt.Errorf("pass at most one positional arg; quote the body: %v", args)
}

When it happens

Trigger: Running e.g. 'caddy respond hello world' or 'caddy respond 200 "ok" extra' — the parser sees NArg() > 1 and rejects.

Common situations: Assuming respond takes body-then-status like other tools; copy-pasting multi-word bodies unquoted ('caddy respond hello world' instead of quoting).

Related errors

• module name is required
• at least one package name must be specified
• invalid module name: %v
• unflagged argument \"%s\" is overridden by flags
• invalid header flag: %v

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