caddyserver/caddy · error

paths are not allowed: %s

Error message

paths are not allowed: %s

What it means

The --from address parsed but contains a path component. The reverse-proxy quick command builds a site address, and paths are not permitted in the downstream listener address (routing on paths is a config-file concern, not a CLI flag).

Source

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

	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 == "" {
		switch fromAddr.Scheme {
		case "http":
			fromAddr.Port = httpPort
		case "https":
			fromAddr.Port = httpsPort
		}
	}

	// set up the upstream address; assume missing information from given parts

View on GitHub (pinned to 50e54ee279)

Solutions

1. Remove the path from --from: 'caddy reverse-proxy --from example.com --to localhost:8080'.
2. If path-scoped proxying is needed, write a Caddyfile with 'handle_path /api/*' or matchers instead of the quick command.
3. Use 'caddy adapt' on that Caddyfile to inspect the resulting JSON.

Example fix

# before
caddy reverse-proxy --from example.com/api --to localhost:8080

# after (path-scoped)
# Caddyfile: example.com { handle_path /api/* { reverse_proxy localhost:8080 } }

a, err := httpcaddyfile.ParseAddress(from)
if err != nil {
    return err
}
if a.Path != "" {
    return fmt.Errorf("--from %q must not contain a path; use a Caddyfile for path matching", from)
}

When it happens

Trigger: 'caddy reverse-proxy --from example.com/api ...' — any --from value with a '/' after the host.

Common situations: Trying to scope the proxy to a path prefix using the flag, mirroring how one might write it in a Caddyfile site block.

Related errors

• invalid downstream address %s: %v
• invalid to flag: %v
• --to is required
• invalid upstream address %s: %v
• invalid header flag: %v

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