caddyserver/caddy · error

parsing listener address: %v

Error message

parsing listener address: %v

What it means

After placeholder replacement, parseAdminListenAddr passes the admin address to ParseNetworkAddress. If the string is not a valid network address (network prefix, host, port), parsing fails and the error is wrapped as 'parsing listener address'. The admin endpoint accepts exactly one address, so even syntactically valid multi-address forms will surface here or in the subsequent port-range check.

Source

Thrown at admin.go:1401

	if e.Err != nil {
		return e.Err.Error()
	}
	return e.Message
}

// parseAdminListenAddr extracts a singular listen address from either addr
// or defaultAddr, returning the network and the address of the listener.
func parseAdminListenAddr(addr string, defaultAddr string) (NetworkAddress, error) {
	input, err := NewReplacer().ReplaceOrErr(addr, true, true)
	if err != nil {
		return NetworkAddress{}, fmt.Errorf("replacing listen address: %v", err)
	}
	if input == "" {
		input = defaultAddr
	}
	listenAddr, err := ParseNetworkAddress(input)
	if err != nil {
		return NetworkAddress{}, fmt.Errorf("parsing listener address: %v", err)
	}
	if listenAddr.PortRangeSize() != 1 {
		return NetworkAddress{}, fmt.Errorf("must be exactly one listener address; cannot listen on: %s", listenAddr)
	}
	return listenAddr, nil
}

// decodeBase64DERCert base64-decodes, then DER-decodes, certStr.
func decodeBase64DERCert(certStr string) (*x509.Certificate, error) {
	derBytes, err := base64.StdEncoding.DecodeString(certStr)
	if err != nil {
		return nil, err
	}
	return x509.ParseCertificate(derBytes)
}

type loggableURLArray []*url.URL

View on GitHub (pinned to 50e54ee279)

Solutions

1. Correct the address to the form [network/]host:port, e.g. 'localhost:2019' or 'unix//run/caddy/admin.sock'.
2. Remove URL-style components — no scheme, no path: 'admin localhost:2019', not 'admin https://localhost:2019'.
3. For unix sockets use the unix network prefix: admin unix//run/caddy/admin.sock.
4. Validate the address with caddy adapt (or ParseNetworkAddress in a scratch program) before deploying.

Example fix

// before
admin https://localhost:2019

// after
admin localhost:2019

if _, err := caddy.ParseNetworkAddress(adminAddr); err != nil {
    return fmt.Errorf("invalid admin address %q: %w", adminAddr, err)
}

When it happens

Trigger: Admin listen values like 'localhost:20a0' (non-numeric port), 'unix/' without a socket path, 'tcp/localhost:notaport', an empty host with ':2019:extra', or a network Caddy does not recognize (e.g. 'foobar/localhost:2019'). Triggered during 'caddy run'/'caddy start' or any admin config load that changes Admin.Listen.

Common situations: Typos in the admin block of a Caddyfile; copy-pasting an HTTP site address (with scheme or path, e.g. 'https://localhost:2019') into the admin directive; forgetting the port; using a unix socket path without the 'unix/' network prefix.

Related errors

• must be exactly one listener address; cannot listen on: %s
• indexing config: %v
• %s: %s field must be a string or number
• duplicate ID '%s' found at %s and %s
• unknown object ID '%s'

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