labstack/echo · critical

ErrInvalidListenerNetwork

ErrInvalidListenerNetwork

Error message

invalid listener network

What it means

ErrInvalidListenerNetwork is a sentinel for an invalid network type passed to the listener configuration. StartConfig.ListenerNetwork defaults to "tcp" and is forwarded to net.ListenConfig.Listen; valid values include tcp, tcp4, tcp6, unix, etc. An unrecognized network string causes the listener to fail to start.

Source

Thrown at httperror.go:35

	ErrNotFound                    = &httpError{http.StatusNotFound}              // 404
	ErrMethodNotAllowed            = &httpError{http.StatusMethodNotAllowed}      // 405
	ErrRequestTimeout              = &httpError{http.StatusRequestTimeout}        // 408
	ErrStatusRequestEntityTooLarge = &httpError{http.StatusRequestEntityTooLarge} // 413
	ErrUnsupportedMediaType        = &httpError{http.StatusUnsupportedMediaType}  // 415
	ErrTooManyRequests             = &httpError{http.StatusTooManyRequests}       // 429
	ErrInternalServerError         = &httpError{http.StatusInternalServerError}   // 500
	ErrBadGateway                  = &httpError{http.StatusBadGateway}            // 502
	ErrServiceUnavailable          = &httpError{http.StatusServiceUnavailable}    // 503
)

// The following errors fall into 500 (InternalServerError) category
var (
	ErrValidatorNotRegistered = errors.New("validator not registered")
	ErrRendererNotRegistered  = errors.New("renderer not registered")
	ErrInvalidRedirectCode    = errors.New("invalid redirect status code")
	ErrCookieNotFound         = errors.New("cookie not found")
	ErrInvalidCertOrKeyType   = errors.New("invalid cert or key type, must be string or []byte")
	ErrInvalidListenerNetwork = errors.New("invalid listener network")
)

// HTTPStatusCoder is an interface that errors can implement to produce status code for HTTP response
type HTTPStatusCoder interface {
	StatusCode() int
}

// StatusCode returns status code from err if it implements HTTPStatusCoder interface.
// If err does not implement the interface, it returns 0.
func StatusCode(err error) int {
	var sc HTTPStatusCoder
	if errors.As(err, &sc) {
		return sc.StatusCode()
	}
	return 0
}

// ResolveResponseStatus returns the Response and HTTP status code that should be (or has been) sent for rw,

View on GitHub (pinned to 05489dc173)

Solutions

1. Use "tcp" for standard TCP (IPv4+IPv6), "tcp4" / "tcp6" for specific IP versions, or "unix" for Unix domain sockets
2. Omit ListenerNetwork to accept the default "tcp"
3. If you need a custom listener, provide your own net.Listener via StartConfig.Listener instead

Example fix

// before
cfg := echo.StartConfig{
    ListenerNetwork: "http",
    Address:         ":8080",
}

// after
cfg := echo.StartConfig{
    ListenerNetwork: "tcp",
    Address:         ":8080",
}

var validNetworks = map[string]bool{"tcp": true, "tcp4": true, "tcp6": true, "unix": true, "unixpacket": true}
func validListenerNetwork(n string) bool { return validNetworks[n] }
if !validListenerNetwork(cfg.ListenerNetwork) {
    return fmt.Errorf("invalid listener network: %s", cfg.ListenerNetwork)
}

if err := echo.StartServer(cfg); err != nil {
    if errors.Is(err, echo.ErrInvalidListenerNetwork) {
        log.Fatal("listener network must be tcp/tcp4/tcp6/unix")
    }
    return err
}

When it happens

Trigger: Setting StartConfig.ListenerNetwork (or the equivalent Echo listener config) to an unrecognized value like "http", "ip", or a typo such as "tcp". The net.Listen call fails and the server does not start.

Common situations: Typo in the network string. Confusing the network type with the scheme (http/https). Trying to use a network not supported on the target OS.

Related errors

• ErrValidatorNotRegistered
• ErrInvalidCertOrKeyType
• echo basic-auth middleware requires a validator function
• echo body-dump middleware requires a handler function
• invalid gzip level

AI-assisted analysis of labstack/echo@05489dc173 (2026-08-04). Data as JSON: /data/errors/ba5dbcec6efac9a0.json. Report an issue: GitHub.