Module errors 

Custom 404 / 500 page helpers.

Two pieces of AppBuilder state plug together with the existing templates engine to deliver the “drop a 404.html in your templates dir” experience:

• not_found_template(name) — installs a fallback that renders the named template with { path } in scope and returns 404.
• server_error_template(name) — wraps the router with a panic-catching tower-http layer that renders the named template on any handler panic and returns 500.

Gap 35 extensions:

• on_server_error(hook) — an opt-in hook that fires before the 500 template is rendered. The closure receives the error message and the request path. Runs synchronously on the error path (panic or Err propagated as a 500). Cannot change the response; used for logging, Sentry dispatch, etc.
• Default Tailwind 404/500 templates — shipped as embedded strings so they work without any templates/ directory on disk. Used when the user hasn’t set their own template name via the builder. Opt-out via App::builder().disable_default_error_pages().
• Dev-mode error detail — when settings.environment == Dev, the 500 template receives an error_chain context variable listing the full std::error::Error source chain. In prod the variable is empty.

Both the 404 and 500 fallbacks are opt-in. When unset (and default pages are disabled), the fallback returns plain-text “Not Found” and panics propagate axum-style (log + empty 500 body).

The 404 path composes with SlashRedirect — if the redirect probe finds an alternate, it 308s; otherwise the configured not-found template renders. Users get one consistent 404 page across normal misses and slash-redirect dead-ends.

Structs

Render500State

State for the response-rendering middleware. Cloned per-request; both fields are cheap to clone (Option<String> + Option<Arc<...>>).

RenderErrorState

State for the general error-page middleware: a status → template-name map. Cloned per request (an Arc, cheap).

Constants

DEFAULT_404_HTML

Default 404 page: centered, inline Tailwind utility classes. Degrades gracefully without Tailwind loaded — the page is functional even as unstyled HTML.

DEFAULT_404_TEMPLATE_NAME

DEFAULT_500_HTML

Default 500 page: same shape as the 404. In dev mode the template receives error_display, error_chain (vec of source strings), and request_path context variables that render into an expandable detail block. In prod those variables are empty strings / empty vecs.

DEFAULT_500_TEMPLATE_NAME

Functions

collect_error_chain

Walk the std::error::Error::source() chain and collect every Display message into a Vec<String>. The first entry is the top-level error itself; subsequent entries are its causes.

fire_server_error_hook

Build an axum fallback or middleware that converts a handler Err response into a 500 with optional dev-mode detail and hook notification.

not_found_fallback

Build an axum fallback handler that renders the configured 404 template. Used when not_found_template is set but slash_redirect is Off — App::build skips the slash redirect path and installs this directly.

render_500_middleware

Middleware that intercepts plain-text 500 responses and re-renders them through the configured server_error_template (or the embedded default when enabled). Already-HTML 500 responses pass through untouched — those were rendered by CatchPanicLayer (panics) or by the handler itself.

render_error_middleware

Middleware that styles error responses for ANY registered status code (e.g. 429, 403, 410) the way render_500_middleware does for 500. After the handler runs, if the response status has a registered template and the body isn’t already HTML, the body text is captured as the message and the template is rendered in its place — preserving the original status code.

render_not_found

Render the configured 404 template with { path } in scope, or fall back to the plain-text response when no template is set or rendering fails.

server_error_panic_handler

Build the panic-handler closure for tower_http::catch_panic::CatchPanicLayer::custom.

Type Aliases

ServerErrorHook

Shared callback type for the on_server_error hook.