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.

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

• adding route without handler function
• echo basic-auth middleware requires a validator function
• echo body-dump middleware requires a handler function
• ErrInvalidCertOrKeyType
• ErrValidatorNotRegistered

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

Appendix: 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)