caddyserver/caddy · error

--to is required

Error message

--to is required

What it means

The 'caddy reverse-proxy' command was invoked without any --to flag (the slice parsed fine but is empty). --to defines the upstream backend address(es) and is mandatory, so Caddy exits with ExitCodeFailedStartup immediately.

Source

Thrown at modules/caddyhttp/reverseproxy/command.go:106

	caddy.TrapSignals()

	from := fs.String("from")
	changeHost := fs.Bool("change-host-header")
	insecure := fs.Bool("insecure")
	disableRedir := fs.Bool("disable-redirects")
	internalCerts := fs.Bool("internal-certs")
	accessLog := fs.Bool("access-log")
	debug := fs.Bool("debug")

	httpPort := strconv.Itoa(caddyhttp.DefaultHTTPPort)
	httpsPort := strconv.Itoa(caddyhttp.DefaultHTTPSPort)

	to, err := fs.GetStringSlice("to")
	if err != nil {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("invalid to flag: %v", err)
	}
	if len(to) == 0 {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("--to is required")
	}

	// set up the downstream address; assume missing information from given parts
	fromAddr, err := httpcaddyfile.ParseAddress(from)
	if err != nil {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("invalid downstream address %s: %v", from, err)
	}
	if fromAddr.Path != "" {
		return caddy.ExitCodeFailedStartup, fmt.Errorf("paths are not allowed: %s", from)
	}
	if fromAddr.Scheme == "" {
		if fromAddr.Port == httpPort || fromAddr.Host == "" {
			fromAddr.Scheme = "http"
		} else {
			fromAddr.Scheme = "https"
		}
	}
	if fromAddr.Port == "" {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Add --to pointing at the backend, e.g. 'caddy reverse-proxy --from example.com --to localhost:8080'.
2. Verify the flag name is exactly --to (not --upstream or --backend).
3. For multiple backends repeat or comma-separate values per the flag's slice semantics.

Example fix

# before
caddy reverse-proxy --from example.com

# after
caddy reverse-proxy --from example.com --to localhost:8080

if len(os.Args) > 0 { /* parse flags first */ }
to := fs.StringSlice("to", nil, "upstream address")
if err := fs.Parse(os.Args[1:]); err != nil { return err }
if len(*to) == 0 {
    return fmt.Errorf("--to is required: specify the backend as host[:port] or scheme://host[:port]")
}

When it happens

Trigger: Running 'caddy reverse-proxy' with only --from, or omitting --to entirely; also typos like --dest that silently leave --to unset.

Common situations: Copy-pasting an example command and deleting the --to part; assuming the proxy forwards to a default port.

Related errors

• invalid to flag: %v
• invalid downstream address %s: %v
• paths are not allowed: %s
• invalid upstream address %s: %v
• invalid header flag: %v

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