Skip to content

docs(group): explain how group catch-all NotFound routes replace RouteNotFound handlers - #3155

Merged
vishr merged 9 commits into
masterfrom
docs/group-route-not-found-order
Oct 5, 2026
Merged

vishr merged 9 commits into
masterfrom
docs/group-route-not-found-order

Conversation

@vishr

@vishr vishr commented Oct 5, 2026 •

Copy link
Copy Markdown
Member

When a group has middlewares, Group#Use() registers catch-all RouteNotFound routes for the group prefix and prefix + /* so that the middlewares also run for unmatched paths. A custom NotFound handler registered for those paths before that call is replaced. This is by design (#2411, TestGroup_RouteNotFoundWithMiddleware), but the Group.RouteNotFound doc did not say so.

This documentation-only change adds a note to Group.RouteNotFound that states the rule:

  • The catch-all routes: each Group#Use() call that leaves the group with middlewares (re)registers them with the group middlewares, unless the Echo-wide Config.NoGroupAutoRegister404Routes is set. Echo#Group() and Group#Group() make this call when the new group has own or inherited middlewares.
  • Which route wins: for the same route path the last registered NotFound route wins, and it runs only the group middlewares it was registered with. The catch-alls replace handlers registered earlier for those paths by any group or by Echo, and a handler registered later replaces them.
  • Practical advice: register custom handlers on the group after the last such call for its prefix to keep its middlewares.
  • Non-overwriting routers: on a Router that does not allow overwriting routes, that registration panics. Use the router-wide RouterConfig.NotFoundHandler (see TestGroup_RouteNotFoundUsesRouterConfig), or set Config.NoGroupAutoRegister404Routes and register both paths yourself on the group whose middlewares should run for them.

Every statement in the note was checked with throwaway tests against the default, non-overwriting, NotFoundHandler, and ConcurrentRouter router configurations.

Refs #3153

vishr added 8 commits October 5, 2026 11:19
Group.Use registers catch-all "" and "/*" RouteNotFound routes so group
middleware runs for unmatched paths, which replaces custom handlers that were
registered for those paths earlier (#3153).