What causes "only tcp, tcp4, or tcp6 is supported " in valyala/fasthttp?

Pass one of 'tcp', 'tcp4', or 'tcp6' to NewListener

only tcp, tcp4, or tcp6 is supported

Error message

only tcp, tcp4, or tcp6 is supported

What it means

getSockaddr validates the network string passed to NewListener and only supports 'tcp', 'tcp4', and 'tcp6'; anything else falls into the default branch and returns this error. The tcplisten package builds raw sockaddr structures, so non-TCP networks (udp, unix, etc.) are simply not implemented. Note the message concatenates the offending network string after a trailing space.

Source

Thrown at tcplisten/tcplisten.go:185

		var sa6 unix.SockaddrInet6
		sa6.Port = tcpAddr.Port
		if tcpAddr.IP == nil {
			tcpAddr.IP = net.IPv4(0, 0, 0, 0)
		}
		copy(sa6.Addr[:], tcpAddr.IP.To16())
		if tcpAddr.Zone != "" {
			ifi, err := net.InterfaceByName(tcpAddr.Zone)
			if err != nil {
				return nil, -1, err
			}
			sa6.ZoneId, err = safeIntToUint32(ifi.Index)
			if err != nil {
				return nil, -1, fmt.Errorf("unexpected convert net interface index int to uint32: %w", err)
			}
		}
		return &sa6, unix.AF_INET6, nil
	default:
		return nil, -1, errors.New("only tcp, tcp4, or tcp6 is supported " + network)
	}
}

func safeIntToUint32(i int) (uint32, error) {
	if i < 0 {
		return 0, errors.New("value is negative, cannot convert to uint32")
	}
	ui := uint64(i)
	if ui > math.MaxUint32 {
		return 0, errors.New("value exceeds uint32 max value")
	}
	return uint32(ui), nil
}

func safeIntToUintptr(i int) (uintptr, error) {
	if i < 0 {
		return 0, errors.New("value is negative, cannot convert to uintptr")
	}

View on GitHub (pinned to c96f600972)

Solutions

Pass one of 'tcp', 'tcp4', or 'tcp6' to NewListener
Check the exact case: 'tcp4' not 'TCP4'; lowercase the config value before calling
For UDP or Unix sockets use net.Listen/std library instead of tcplisten

Example fix

// before
ln, err := ctl.NewListener("udp", addr) // error
// after
ln, err := ctl.NewListener("tcp4", addr)

Defensive patterns

Strategy: validation

Validate before calling

var validListenerNetworks = map[string]bool{"tcp": true, "tcp4": true, "tcp6": true}
func validateListenerNetwork(n string) error {
  if !validListenerNetworks[strings.ToLower(n)] {
    return fmt.Errorf("tcplisten supports only tcp/tcp4/tcp6, got %q", n)
  }
  return nil
}

Type guard

func isTCPNetwork(n string) bool {
  switch strings.ToLower(n) { case "tcp", "tcp4", "tcp6": return true }
  return false
}

Try / catch

ln, err := ctl.NewListener(network, addr)
if err != nil {
  if strings.HasPrefix(err.Error(), "only tcp, tcp4, or tcp6 is supported") {
    return fmt.Errorf("bad listener network %q: %w", network, err)
  }
  return err
}

Prevention

Whitelist-validate the network string from config before constructing listeners
Lowercase/trim config values — the check is case-sensitive
Use tcplisten only for TCP; route UDP/Unix sockets to net.Listen
Document supported values where the network is configured

When it happens

Trigger: Calling tcplisten.NewListener(network, ...) with a network value other than 'tcp', 'tcp4', or 'tcp6' — e.g. 'udp', 'unix', 'tcp+' or an empty string — from config or a wrapper that forwards the raw net.Listen network argument.

Common situations: Reusing a generic listener config that contains 'udp' or 'unix' and passing it to tcplisten; user config typo like 'TCP4' (case-sensitive); assuming tcplisten is a drop-in for net.Listen for all networks.

Related errors

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/88e90bfcd7cde3e8. Report an issue: GitHub.