Enum RouterBuildError 

pub enum RouterBuildError {
    InvalidSessionBackend(SessionBackendConfigError),
    InvalidIdempotencyBackend(String),
    InvalidSubmitTokenBackend(String),
    FrameworkRouteOverlap {
        path: String,
        existing: &'static str,
        incoming: &'static str,
    },
    InvalidOpenApiPath {
        field: &'static str,
        value: String,
    },
    DuplicateOpenApiPath {
        path: String,
    },
    OpenApiPathCollision {
        field: &'static str,
        path: String,
    },
    UnregisteredApiVersion {
        route_name: String,
        version: String,
    },
    InvalidMcpPath {
        value: String,
    },
    McpPathCollision {
        path: String,
        method: String,
    },
    DuplicateUserRoute {
        method: String,
        path: String,
        existing: String,
        incoming: String,
    },
    DuplicateNestPrefix {
        prefix: String,
        owners: String,
    },
    ConflictingRouteShape {
        existing: String,
        existing_path: String,
        incoming: String,
        incoming_path: String,
    },
    LocalePrefixPathCollision {
        locale: String,
        path: String,
        generated: String,
    },
}

The refusal AppBuilder::plugin_route_infos and route_listing::collect_route_infos return.

Re-exported from the crate-private router module because both of those are public functions that hand it back: without this, a caller could not name the type, match its variants, or write the signature of a function that forwards it. Errors that can occur during the router build process.

These errors are typically fatal and represent configuration or routing definition issues that must be fixed before the application can start.

Variants

InvalidSessionBackend(SessionBackendConfigError)

The session backend configuration is invalid (e.g. Redis without a URL).

InvalidIdempotencyBackend(String)

The idempotency backend configuration is invalid.

InvalidSubmitTokenBackend(String)

The submit-token backend configuration is invalid for production — an explicit [security.submit_token].backend = "memory" cannot safely deduplicate submits across replicas. Mirrors the idempotency production-memory fail-fast.

FrameworkRouteOverlap

A user-defined route conflicts with a framework-provided route.

Fields

path: String

The HTTP path where the overlap occurred.

existing: &'static str

The name of the existing framework route.

incoming: &'static str

The name of the incoming user route.

InvalidOpenApiPath

An OpenApiConfig path (e.g. openapi_json_path or swagger_ui_path) is not a valid route path (must start with / and be non-empty).

Fields

field: &'static str

Which config field carried the invalid path.

value: String

The offending value from the user’s config.

DuplicateOpenApiPath

openapi_json_path and swagger_ui_path collide on the same URL. Mounting both would cause axum to panic on overlapping method routes at startup.

Fields

path: String

The path that both fields pointed at.

OpenApiPathCollision

An OpenAPI mount path overlaps with an existing GET handler, which would panic at axum::Router::merge time.

Fields

field: &'static str

Which config field carried the colliding path.

path: String

The colliding path.

UnregisteredApiVersion

A route is annotated with an API version that is not registered.

Fields

route_name: String

version: String

InvalidMcpPath

The MCP mount path (from AppBuilder::mount_mcp) is not a valid route path. axum requires paths to start with /, so an invalid path is surfaced here rather than panicking at mount time.

Fields

value: String

The offending mount path.

McpPathCollision

The MCP mount path collides with an existing application route at the same path. Mounting the MCP endpoint there would panic at axum::Router::merge time on overlapping method routes, so this is surfaced as a recoverable error instead.

Fields

path: String

The colliding mount path.

method: String

The HTTP method of the existing route at that path.

DuplicateUserRoute

Two user- or plugin-registered routes resolve to the same (method, path) after scope-prefix resolution. Mounting both would panic inside axum::routing::MethodRouter::merge at startup on overlapping method routes (issue #1012), so the collision preflight surfaces it as a recoverable RouterBuildError BEFORE any router is mounted and names both handlers so the offending call sites are obvious in the log.

Opaque routers registered via AppBuilder::merge or AppBuilder::nest are NOT introspectable through axum’s public API, so a collision that involves one of those routers cannot be detected up front and will still surface as an axum startup panic — the preflight emits a tracing::warn! in that case so operators know the check was skipped (mirrors the existing OpenAPI/MCP merge-router warnings).

Fields

method: String

The HTTP method both handlers registered.

path: String

The URL path both handlers registered (post scope-prefix resolution).

existing: String

The route.name of the first (already-seen) handler.

incoming: String

The route.name of the second (duplicate) handler that triggered the collision.

DuplicateNestPrefix

Two routers were registered at the SAME nest prefix via AppBuilder::nest.

Every nested router is given a fallback before it is mounted (mount_raw_routers), and axum cannot merge two method routers that both have one — nesting the second at a prefix the first already owns panics with “Cannot merge two MethodRouters that both have a fallback” while the router is built.

The declared-route preflight cannot catch this: two sandboxed plugins sharing a prefix while declaring disjoint routes have no route collision at all, and are accepted right up until the second nest panics. A prefix is therefore owned by whoever nests at it first.

Fields

prefix: String

The prefix both routers were nested at.

owners: String

Who claims the prefix, as far as the declared routes reveal.

ConflictingRouteShape

Two user- or plugin-registered routes normalize to the SAME Axum path shape but use DIFFERENT exact path templates — e.g. their capture names differ (/users/{id} vs /users/{slug}) or a normal capture meets a catch-all at the same position (/u/{id} vs /u/{*rest}).

axum’s matchit router rejects the second template as a route conflict before method-router merging, so — unlike an exact-duplicate path, which axum happily merges across distinct HTTP methods (DuplicateUserRoute) — these two templates can never coexist REGARDLESS of method. Issue #1012 surfaces the clash here (naming both handlers and both original templates) instead of letting the matchit conflict panic inside Router::route at startup.

Opaque AppBuilder::merge / AppBuilder::nest routers are exempt for the same reason as DuplicateUserRoute.

Fields

existing: String

The route.name of the first (already-seen) handler.

existing_path: String

The original path template registered by the first handler.

incoming: String

The route.name of the second handler that triggered the conflict.

incoming_path: String

The original path template registered by the second handler.

LocalePrefixPathCollision

Locale-prefix routing (issue #1251) would generate a path that collides with another route already registered at that exact path — e.g. an app defines both /foo and /en/foo while en is a supported locale: the bare-path redirect (mounted at every locale-prefix-eligible path, claiming every HTTP method) already owns /en/foo, so nesting /foo’s content under /en collides and axum panics on the overlapping route at router-construction time. Detected and surfaced as a build error instead (Codex review).

Fields

locale: String

The supported locale whose nest produced the collision.

path: String

The original, locale-prefix-eligible route path that got nested.

generated: String

The resulting generated path (/{locale}{path}) that collides.

Trait Implementations

impl Debug for RouterBuildError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for RouterBuildError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for RouterBuildError

impl Error for RouterBuildError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<SessionBackendConfigError> for RouterBuildError

fn from(source: SessionBackendConfigError) -> Self

Converts to this type from the input type.

impl PartialEq for RouterBuildError

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for RouterBuildError