leptos-rs/leptos · error

<FlatRoutes> should not be used with nested routes.

Error message

<FlatRoutes> should not be used with nested routes.

What it means

The <FlatRoutes> router component only supports flat route structures (no nested child routes). During match building, if a matched route definition produces a child route, the router panics in debug builds because the flat matcher cannot correctly render nested layouts.

Source

Thrown at router/src/flat_router.rs:138

        // release URL lock
        drop(current_url);

        match new_match {
            None => Rc::new(RefCell::new(FlatRoutesViewState {
                view: fallback().into_any().build(),
                id,
                owner,
                params,
                path,
                url,
                matched,
            })),
            Some(new_match) => {
                let (view, child) = new_match.into_view_and_child();

                #[cfg(debug_assertions)]
                if child.is_some() {
                    panic!(
                        "<FlatRoutes> should not be used with nested routes."
                    );
                }

                let mut view = Box::pin(owner.with(|| {
                    provide_context(params_memo);
                    provide_context(url.clone());
                    provide_context(Matched(ArcMemo::from(matched.clone())));

                    ScopedFuture::new(async move {
                        OwnedView::new(view.choose().await)
                    })
                }));

                match view.as_mut().now_or_never() {
                    Some(view) => Rc::new(RefCell::new(FlatRoutesViewState {
                        view: view.into_any().build(),
                        id,

View on GitHub (pinned to 32d20f6c9d)

Solutions

1. Flatten the route definitions so every route is a single segment-free full path with no children, or use explicit full paths for each leaf.
2. Switch from <FlatRoutes> back to <Routes>, which fully supports nested routes.
3. Audit route definitions for children fields / nested route arrays and remove them when keeping FlatRoutes.

Example fix

// before
<FlatRoutes>
  <Route path="admin" view=AdminLayout>
    <Route path="users" view=Users/> // nested -> panic
  </Route>
</FlatRoutes>

// after
<Routes>
  <Route path="admin" view=AdminLayout>
    <Route path="users" view=Users/>
  </Route>
</Routes>
// or flat: <FlatRoutes><Route path="admin/users" view=Users/></FlatRoutes>

// assert no route in the tree has children before using FlatRoutes
fn routes_are_flat(routes: &[RouteDef]) -> bool { routes.iter().all(|r| r.children.is_empty()) }

When it happens

Trigger: Using <FlatRoutes> with a route tree where any route has children — e.g. a parent route like "/admin" containing child routes, or nest( Parent, [children]) style definitions inside FlatRoutes instead of <Routes>.

Common situations: Migrating an existing <Routes> app to <FlatRoutes> for its simpler matching without flattening the route definitions; copying nested route examples into a FlatRoutes component; accidentally nesting routes via layout wrappers.

Related errors

• {location:?} expected context of type {type_name:?} to be pr
• Tried to access a reactive value that has already been dispo
• could not find key for index {index:?} at {caller}
• lazy routes should not be used with hydrate_body(); use hydr
• At {caller}, you call `to_server_error()` or use `server_fn_

AI-assisted analysis of leptos-rs/leptos@32d20f6c9d (2026-09-01). Data as JSON: /api/errors/e973b1775e0d1ced. Report an issue: GitHub.