caddyserver/caddy · error

splitting listener address: %v

Error message

splitting listener address: %v

What it means

A bind directive address (or default_bind value) could not be split by caddy.SplitNetworkAddress into network/host/port components. This runs after scheme/port resolution, on every address from the block's bind pile, before rejoining with the site's port.

Source

Thrown at caddyconfig/httpcaddyfile/addresses.go:335

		if defaultBindValues, ok := options["default_bind"].([]ConfigValue); ok {
			for _, defaultBindValue := range defaultBindValues {
				lnCfgVals = append(lnCfgVals, defaultBindValue.Value.(addressesWithProtocols))
			}
		} else {
			lnCfgVals = []addressesWithProtocols{{
				addresses: []string{""},
				protocols: nil,
			}}
		}
	}

	// use a map to prevent duplication
	listeners := map[string]map[string]struct{}{}
	for _, lnCfgVal := range lnCfgVals {
		for _, lnAddr := range lnCfgVal.addresses {
			lnNetw, lnHost, _, err := caddy.SplitNetworkAddress(lnAddr)
			if err != nil {
				return nil, fmt.Errorf("splitting listener address: %v", err)
			}
			networkAddr, err := caddy.ParseNetworkAddress(caddy.JoinNetworkAddress(lnNetw, lnHost, lnPort))
			if err != nil {
				return nil, fmt.Errorf("parsing network address: %v", err)
			}
			if _, ok := listeners[addr.String()]; !ok {
				listeners[networkAddr.String()] = map[string]struct{}{}
			}
			for _, protocol := range lnCfgVal.protocols {
				listeners[networkAddr.String()][protocol] = struct{}{}
			}
		}
	}

	return listeners, nil
}

// addressesWithProtocols associates a list of listen addresses

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check each bind argument; it must be a bare address, optionally with a network prefix like tcp/ or unix/ (e.g. 'bind 127.0.0.1', 'bind tcp/0.0.0.0', 'bind unix//run/caddy.sock')
2. Remove any scheme (http://) from bind values
3. Read the wrapped SplitNetworkAddress error for the precise reason
4. Validate the whole file with `caddy adapt --config Caddyfile`

Example fix

# before
bind http://127.0.0.1
# after
bind 127.0.0.1

for _, b := range bindAddresses {
    if _, _, _, err := caddy.SplitNetworkAddress(b); err != nil {
        return fmt.Errorf("bad bind address %q: %w", b, err)
    }
}

When it happens

Trigger: bind (or default_bind) with a malformed address: empty host where one is required, invalid network prefix syntax (e.g. 'tcp/:' or 'unix/' without a path), stray brackets/colons, or a port appearing where only host/network are expected.

Common situations: Typos like 'bind 127.0.0.1:' , 'bind tcp//eth0', or copy-pasting full URLs (http://127.0.0.1) into bind instead of bare addresses.

Related errors

• server block %d, key %d (%s): determining listener address:
• listening on %s: %v
• invalid action type
• parsing listener address: %v
• %s app module: start: %v

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