caddyserver/caddy · error

unsupported network

Error message

unsupported network

What it means

The network of local_address fell through the switch on tcp/tcp4/tcp6, unix/unixgram/unixpacket, and udp/udp4/udp6 families. This happens when caddy.ParseNetworkAddressWithDefaults accepted an unusual network string that the transport cannot turn into a dialer LocalAddr.

Source

Thrown at modules/caddyhttp/reverseproxy/httptransport.go:255

		}
		if netaddr.PortRangeSize() > 1 {
			return nil, fmt.Errorf("local_address must be a single address, not a port range")
		}
		switch netaddr.Network {
		case "tcp", "tcp4", "tcp6":
			dialer.LocalAddr, err = net.ResolveTCPAddr(netaddr.Network, netaddr.JoinHostPort(0))
			if err != nil {
				return nil, err
			}
		case "unix", "unixgram", "unixpacket":
			dialer.LocalAddr, err = net.ResolveUnixAddr(netaddr.Network, netaddr.JoinHostPort(0))
			if err != nil {
				return nil, err
			}
		case "udp", "udp4", "udp6":
			return nil, fmt.Errorf("local_address must be a TCP address, not a UDP address")
		default:
			return nil, fmt.Errorf("unsupported network")
		}
	}
	if h.Resolver != nil {
		err := h.Resolver.ParseAddresses()
		if err != nil {
			return nil, err
		}
		d := &net.Dialer{
			Timeout:       time.Duration(h.DialTimeout),
			FallbackDelay: time.Duration(h.FallbackDelay),
		}
		dialer.Resolver = &net.Resolver{
			PreferGo: true,
			Dial: func(ctx context.Context, _, _ string) (net.Conn, error) {
				//nolint:gosec
				addr := h.Resolver.netAddrs[weakrand.IntN(len(h.Resolver.netAddrs))]
				return d.DialContext(ctx, addr.Network, addr.JoinHostPort(0))
			},

View on GitHub (pinned to 50e54ee279)

Solutions

1. Use tcp (default), tcp4, tcp6, or a unix-family network in local_address
2. If you need raw IP sockets, do that in your own app — the HTTP transport only supports TCP/unix local addresses

Example fix

# before (JSON)
{"transport": {"protocol": "http", "local_address": "ip/10.0.0.5"}}
# after (JSON)
{"transport": {"protocol": "http", "local_address": "tcp/10.0.0.5"}}

var okNets = map[string]bool{"tcp": true, "tcp4": true, "tcp6": true, "unix": true, "unixgram": true, "unixpacket": true}
if !okNets[netaddr.Network] {
	return fmt.Errorf("unsupported network %q", netaddr.Network)
}

When it happens

Trigger: Specifying an exotic network in local_address such as `ip`, `ip4`, a custom registered net.Op, or an empty-but-present network string that still parses.

Common situations: Hand-crafted JSON configs (where there is no Caddyfile validation narrowing the values), or wrapping Caddy's address parser in custom tooling that passes through arbitrary network names.

Related errors

• local_address must be a single address, not a port range
• local_address must be a TCP address, not a UDP address
• unsupported HTTP version: %s, supported version: %s
• unsupported network type: %s
• invalid IP address: '%s': %v

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