caddyserver/caddy · error

unsupported network type: %s

Error message

unsupported network type: %s

What it means

In Listen piece assembly, after all registered listener-creation paths run, if err is nil but no listener object was produced, the network type is unsupported. Caddy supports tcp/tcp4/tcp6, udp/udp4/udp6, unix/unixpacket/unixgram, fd/fdgram; anything else falls through with ln == nil.

Source

Thrown at listeners.go:191

	} else {
		if na.IsUnixNetwork() {
			// if this is a unix socket, see if we already have it open
			ln, err = reuseUnixSocket(na.Network, address)
		}

		if ln == nil && err == nil {
			// otherwise, create a new listener
			lnKey := listenerKey(na.Network, address)
			ln, err = listenReusable(ctx, lnKey, na.Network, address, config)
		}
	}

	if err != nil {
		return nil, err
	}

	if ln == nil {
		return nil, fmt.Errorf("unsupported network type: %s", na.Network)
	}

	if IsUnixNetwork(na.Network) {
		isAbstractUnixSocket := strings.HasPrefix(address, "@")
		if !isAbstractUnixSocket {
			err = os.Chmod(address, unixFileMode)
			if err != nil {
				return nil, fmt.Errorf("unable to set permissions (%s) on %s: %v", unixFileMode, address, err)
			}
		}
	}

	return ln, nil
}

// IsUnixNetwork returns true if na.Network is
// unix, unixgram, or unixpacket.
func (na NetworkAddress) IsUnixNetwork() bool {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Use one of the supported networks: tcp, tcp4, tcp6, udp, udp4, udp6, unix, unixpacket, unixgram, fd, fdgram.
2. For plain HTTP words in the address (http://), remove them — Caddy parses host:port, not schemes, in listen addresses.
3. If you truly need another net package network, dial/listen directly with net.Listen rather than Caddy's listener pool.

Example fix

// before
addr, _ := caddy.ParseNetworkAddress("tpc://:80")
ln, err := addr.Listen(ctx)
// after
addr, _ := caddy.ParseNetworkAddress("tcp/:80")
ln, err := addr.Listen(ctx)

var supportedNetworks = map[string]bool{
    "tcp": true, "tcp4": true, "tcp6": true,
    "udp": true, "udp4": true, "udp6": true,
    "unix": true, "unixpacket": true, "unixgram": true,
    "fd": true, "fdgram": true,
}

func networkOK(n string) bool { return supportedNetworks[n] }

func isSupportedNetwork(n string) bool {
    switch n {
    case "tcp", "tcp4", "tcp6", "udp", "udp4", "udp6",
         "unix", "unixpacket", "unixgram", "fd", "fdgram":
        return true
    }
    return false
}

When it happens

Trigger: Calling caddy.Listen with a NetworkAddress whose Network is misspelled or unsupported: 'tpc', 'http', 'ip', 'socket', or an empty network that slipped through earlier validation.

Common situations: Typos in the listen network in JSON config or API calls; custom code calling caddy.Listen with arbitrary net package networks (ip, ip4) that Caddy deliberately does not handle.

Related errors

• invalid IP address: '%s': %v
• parsing CIDR expression: '%s': %v
• parsing listener address: %v
• must be exactly one listener address; cannot listen on: %s
• indexing config: %v

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