labstack/echo · error · AddRouteError

adding route without handler function

Error message

adding route without handler function

What it means

Returned by DefaultRouter.Add (router.go:517-519) when the Route has a nil Handler and Method is neither RouteNotFound nor http.MethodOptions — those two fall back to router-level default handlers, every other method requires an explicit handler.

Source

Thrown at router.go:518

	return &AddRouteError{
		Method: route.Method,
		Path:   route.Path,
		Err:    err,
	}
}

// Add registers a new route for method and path with matching handler.
func (r *DefaultRouter) Add(route Route) (RouteInfo, error) {
	allowOverwritingRoute := r.allowOverwritingRoute || route.allowOverwrite

	if route.Handler == nil {
		switch route.Method {
		case RouteNotFound:
			route.Handler = r.notFoundHandler
		case http.MethodOptions:
			route.Handler = r.optionsMethodHandler
		default:
			return RouteInfo{}, newAddRouteError(route, errors.New("adding route without handler function"))
		}
	}

	method := route.Method
	path := normalizePathSlash(route.Path)

	h := applyMiddleware(route.Handler, route.Middlewares...)
	if !allowOverwritingRoute {
		for _, rr := range r.routes {
			if route.Method == rr.Method && route.Path == rr.Path {
				return RouteInfo{}, newAddRouteError(route, errors.New("adding duplicate route (same method+path) is not allowed"))
			}
		}
	}
	var headH HandlerFunc
	if r.autoHandleHEAD && method == http.MethodGet {
		headH = wrapHeadHandler(h)
	}

View on GitHub (pinned to 05489dc173)

Solutions

1. Provide a non-nil Handler in the Route
2. Prefer the high-level helpers e.GET/e.POST which always set a handler
3. Use Method RouteNotFound or http.MethodOptions only when you intend the router default fallback

Example fix

// before
_, err := e.Router().Add(echo.Route{Method: http.MethodGet, Path: "/x"})
// after
_, err := e.Router().Add(echo.Route{Method: http.MethodGet, Path: "/x", Handler: h})

if route.Handler == nil && route.Method != echo.RouteNotFound && route.Method != http.MethodOptions {
    return errors.New("handler required for method " + route.Method)
}
_, err := e.Router().Add(route)

When it happens

Trigger: Calling e.Router().Add(echo.Route{Method: http.MethodGet, Path: "/x"}) with Handler left nil; building a Route struct manually and forgetting the Handler field; a conditional handler that resolved to nil.

Common situations: Using the low-level Add API instead of e.GET/e.POST; refactors that drop the handler assignment; dynamic handler wiring that produced nil.

Related errors

• ErrValidatorNotRegistered
• ErrInvalidCertOrKeyType
• ErrInvalidListenerNetwork
• echo basic-auth middleware requires a validator function
• echo body-dump middleware requires a handler function

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