caddyserver/caddy · error

parsing key: %v

Error message

parsing key: %v

What it means

While mapping server-block keys to listeners, a site address key failed ParseAddress. This validates the site label syntax (scheme://host:port/path) before normalization; any parse failure is wrapped as 'parsing key'.

Source

Thrown at caddyconfig/httpcaddyfile/addresses.go:100

) (map[string]map[string][]serverBlock, error) {
	addrToProtocolToServerBlocks := map[string]map[string][]serverBlock{}

	type keyWithParsedKey struct {
		key       caddyfile.Token
		parsedKey Address
	}

	for i, sblock := range originalServerBlocks {
		// within a server block, we need to map all the listener addresses
		// implied by the server block to the keys of the server block which
		// will be served by them; this has the effect of treating each
		// key of a server block as its own, but without having to repeat its
		// contents in cases where multiple keys really can be served together
		addrToProtocolToKeyWithParsedKeys := map[string]map[string][]keyWithParsedKey{}
		for j, key := range sblock.block.Keys {
			parsedKey, err := ParseAddress(key.Text)
			if err != nil {
				return nil, fmt.Errorf("parsing key: %v", err)
			}
			parsedKey = parsedKey.Normalize()

			// a key can have multiple listener addresses if there are multiple
			// arguments to the 'bind' directive (although they will all have
			// the same port, since the port is defined by the key or is implicit
			// through automatic HTTPS)
			listeners, err := st.listenersForServerBlockAddress(sblock, parsedKey, options)
			if err != nil {
				return nil, fmt.Errorf("server block %d, key %d (%s): determining listener address: %v", i, j, key.Text, err)
			}

			// associate this key with its protocols and each listener address served with them
			kwpk := keyWithParsedKey{key, parsedKey}
			for addr, protocols := range listeners {
				protocolToKeyWithParsedKeys, ok := addrToProtocolToKeyWithParsedKeys[addr]
				if !ok {
					protocolToKeyWithParsedKeys = map[string][]keyWithParsedKey{}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped parse error for the exact reason, then fix the key text on the site block line
2. If using {$ENV} placeholders in site addresses, verify the variables are set in Caddy's environment
3. Validate with `caddy adapt --config Caddyfile` to iterate quickly
4. Check the Caddyfile site-address syntax docs for scheme/host/port/path combinations

Example fix

# before
https://example.com:notaport {
}
# after
https://example.com:8443 {
}

for _, key := range blockKeys {
    if _, err := httpcaddyfile.ParseAddress(key); err != nil {
        return fmt.Errorf("bad site address %q: %w", key, err)
    }
}

When it happens

Trigger: A Caddyfile site block key is malformed: bad host characters, invalid port (non-numeric), wrong scheme:// placement, or a placeholder/variable that ParseAddress cannot interpret as a concrete address.

Common situations: Typos like 'example.com:' (empty port), 'https://example.com:notaport', or using placeholders like {$SITE} when the environment variable is unset (leaving an unparseable key).

Related errors

• server block %d, key %d (%s): determining listener address:
• the scheme wss:// is only supported in browsers; use https:/
• the scheme ws:// is only supported in browsers; use http://
• unsupported URL scheme %s://
• [%s] scheme and port violate convention

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