Axum-Claude-Skill-Package

Use when auditing or reviewing existing Axum code, a diff, or a single file for correctness, reliability, and security defects, when a code review must flag Axum-specific mistakes, or when checking an Axum service against the package best practices before a merge or a deploy. Prevents shipping the 16 known Axum anti-patterns: 0.7 path syntax on 0.8, body extractor not last, non-IntoResponse handler returns, blocking calls in async handlers, per-request database pools, hardcoded secrets, missing graceful shutdown, and more. Covers a 10-category review checklist, a three-level severity model (blocker, warning, suggestion), the structured findings output format, and cross-references to all 28 other Axum skills that own each fix. Keywords: axum code review, audit axum, review checklist, anti-pattern, severity, blocker warning suggestion, structured findings, is my axum code correct, what is wrong with this handler, find bugs in axum code, check an axum service before deploy, how do I review axum code.

Use when the request is to build a complete Axum service from scratch rather than to fix one isolated piece: "build me an Axum API", "scaffold a Rust web service", "set up a new Axum project", or when a half-built service needs the missing production layers identified and ordered. Prevents scaffolding in the wrong order (layering before routes, choosing a framework before pinning a version), shipping a service with no graceful shutdown or permissive CORS, and reinventing decisions that a dedicated skill in this package already owns. Covers the ordered core to syntax to impl to errors build sequence, a service-type classifier, the Cargo.toml dependency baseline, the minimal-to-production checklist, and which of the other 28 Axum skills owns each decision. Keywords: axum scaffold, build axum service, new axum project, axum project structure, scaffold rust web service, axum boilerplate, where do I start with axum, how do I structure an axum app, axum service checklist, axum production checklist, axum Cargo.toml,

Use when an Axum extractor fails and you need control over the HTTP error: customizing a Json/Path/Query rejection, returning a JSON error body instead of Axum's plain text, building a unified API error type, or upgrading 0.7 to 0.8 and Option extractors suddenly return 4xx. Prevents the non-exhaustive match compile error on rejection enums, inventing a wrong status code instead of reusing the rejection's own, and the silent 0.8 behavior change where Option no longer swallows malformed input. Covers the Rejection associated type, the axum::extract::rejection module, Result handler arguments, axum-extra WithRejection, derive(FromRequest) with rejection(...), hand-written custom extractors, and OptionalFromRequest. Keywords: axum rejection, extractor rejection, JsonRejection, PathRejection, QueryRejection, FormRejection, WithRejection, from_request rejection, derive FromRequest, OptionalFromRequest, non_exhaustive match error, body_text, status, customize extractor error, 400 instead of JSON, plain text error b

Use when the compiler rejects an Axum handler with "the trait bound ... Handler<_, _> is not satisfied", when a function will not register on a route, when the error block names Handler with inference placeholders and lists unrelated impls as help, or when a handler argument or return type silently breaks compilation. Prevents passing a non-extractor argument, placing a body extractor before a parts extractor, returning a type that is not IntoResponse, writing a plain synchronous fn, and producing a !Send future by holding a guard across await. Covers the opaque E0277 trait-bound error, the five root causes, the axum-macros #[debug_handler] diagnostic macro and its macros feature, the state= override, and a symptom-to-cause-to-fix decision tree. Keywords: Handler is not satisfied, trait bound is not satisfied, E0277, debug_handler, axum-macros, macros feature, FromRequestParts, FromRequest, IntoResponse, blanket impl, !Send future, MutexGuard across await, handlers must be async functions, cannot find __axum_

Use when a handler must return an error, when adding a custom error type to an Axum service, when the question mark operator will not compile inside a handler, when anyhow::Error does not implement IntoResponse, or when a fallible tower middleware Service is rejected by the Router. Prevents calling unwrap or panic in handlers, returning a 500 where a 404 or 422 belongs, leaking internal error text to clients, and trying to impl IntoResponse for anyhow::Error directly against the orphan rule. Covers the infallible-handler model, the AppError enum with IntoResponse and From impls, thiserror versus anyhow, combining a thiserror enum with an anyhow catch-all variant, and HandleError / HandleErrorLayer for fallible tower::Service middleware. Keywords: IntoResponse, AppError, thiserror, anyhow, HandleError, HandleErrorLayer, Infallible, From impl, question mark operator, orphan rule, the trait IntoResponse is not implemented, anyhow does not implement IntoResponse, handler panics instead of returning a response, 50

Use when deploying an Axum service to production, containerizing it with Docker, or when a SIGTERM from Docker, Kubernetes, or systemd kills in-flight requests on every restart or rolling deploy. Prevents dropped requests on shutdown, 1.5 GB images from single-stage builds, a full dependency recompile on every source change, and binaries that fail to start in a scratch container. Covers release builds, static musl binaries, multi-stage Dockerfiles, cargo-chef dependency-layer caching, with_graceful_shutdown plus a SIGINT/SIGTERM signal future, closing the DB pool on shutdown, and container hygiene (bind 0.0.0.0, env-var config, non-root user). Keywords: axum deployment, Docker, with_graceful_shutdown, shutdown_signal, SIGTERM, SIGINT, graceful shutdown, cargo-chef, multi-stage build, musl, x86_64-unknown-linux-musl, scratch image, distroless, TimeoutLayer, release build, requests dropped on deploy, container exits immediately, image too big, how do I dockerize axum, why does my binary not run in scratch.

Use when generating an OpenAPI 3 specification and a Swagger UI for an Axum service: documenting handlers, describing request and response schemas, or serving an interactive API explorer. Prevents the hand-written spec that silently drifts from the real handlers, the route registered on the Router but missing from the spec, the wrong {param} versus :id path syntax, and pinning three independently-versioned crates to mismatched releases. Covers utoipa derive macros ToSchema, OpenApi, IntoParams, IntoResponses, ToResponse, the #[utoipa::path] attribute, utoipa-swagger-ui SwaggerUi, and utoipa-axum OpenApiRouter with the routes! macro that registers a handler once for both routing and the spec. Keywords: axum openapi, utoipa, utoipa-axum, utoipa-swagger-ui, ToSchema, utoipa::path macro, derive OpenApi, OpenApiRouter, routes macro, split_for_parts, SwaggerUi, swagger ui, api documentation drift, spec out of date, route documented but returns 404, schema missing from spec, swagger ui blank page, how do I add swagg

Use when adding structured logging or request tracing to an Axum service, when wiring a tracing-subscriber, when instrumenting handlers, when log timings look interleaved or spans nest under the wrong parent, or when exporting spans to an OpenTelemetry backend. Prevents holding a Span::enter guard across an await point, calling init twice, missing the SubscriberExt and SubscriberInitExt imports, spanning on the raw URI instead of MatchedPath, recording a span field that was never declared, and interpolating values into the log message with format. Covers tracing-subscriber registry and EnvFilter and fmt::layer, the tower-http TraceLayer::new_for_http middleware and its six hooks, the tracing event macros, the instrument attribute, the Debug and Display field sigils, the span-guard-across-await rule, and OpenTelemetry export. Keywords: tracing, tracing-subscriber, registry, EnvFilter, RUST_LOG, fmt layer, TraceLayer, new_for_http, make_span_with, on_response, on_failure, info macro, error macro, instrument, Sp

Use when adding a SQL database to an Axum service, when wiring a sqlx connection pool into router state, when running queries or transactions inside handlers, or when migrating a DatabaseConnection extractor from Axum 0.7 to 0.8. Prevents creating a new pool per request, wrapping PgPool in Arc, wrapping PgPool in a Mutex, calling unwrap on query results, and omitting acquire_timeout so a saturated pool hangs every request forever. Covers sqlx PgPoolOptions, the Pool reference-counted Clone, with_state, compile-time query macros versus runtime query functions, fetch_one and fetch_optional and fetch_all and execute, transactions with drop-rollback, the DatabaseConnection FromRequestParts extractor, and pool sizing. Keywords: sqlx, PgPool, MySqlPool, SqlitePool, PgPoolOptions, max_connections, acquire_timeout, with_state, query macro, query_as, query_scalar, fetch_one, fetch_optional, fetch_all, execute, transaction, begin commit rollback, FromRequestParts, PoolConnection, FromRef, connection pool exhausted, too

Use when writing tests for an Axum application, when a handler test panics with MissingJsonContentType or returns 415, when a second request against the same app fails to compile, or when integration tests under tests/ cannot see the app() function. Prevents reusing a consumed oneshot service, posting JSON without a Content-Type header, and building ad-hoc routers that drift from the real app wiring. Covers the tower ServiceExt::oneshot pattern, the axum-test TestServer API, http_body_util BodyExt::collect for reading response bodies, the shared app() constructor, and the src/lib.rs plus tests/ directory layout. Keywords: axum testing, TestServer, oneshot, ServiceExt, axum-test, BodyExt collect, into_service, ready call, MissingJsonContentType, 415 Unsupported Media Type, assert_status_ok, assert_json, tokio::test, how do I test an axum handler, my test will not compile a second request, integration test cannot find app, test panics on json post.

Use when validating an incoming JSON request body in an Axum handler: an email field, a string length bound, a numeric range, a password-confirm match, or any domain rule the value must satisfy before the handler trusts it. Prevents accepting semantically invalid input, returning a 400 where a 422 belongs, scattering validate() calls across every handler, and the runtime panic from compiling a regex on every request. Covers the validator crate #[derive(Validate)] attributes, a ValidatedJson<T> custom FromRequest extractor that deserializes then runs .validate() and returns 422, the structured ValidationErrors JSON body, garde as a context-aware alternative, and the Axum 0.7 versus 0.8 #[async_trait] difference on the extractor impl. Keywords: axum validation, validator crate, derive Validate, ValidationError, ValidationErrors, ValidatedJson, FromRequest extractor, JsonRejection, 422 Unprocessable Entity, validate email, length range custom regex nested, must_match, garde, async_trait, invalid input accepted,

Use when adding stateless JWT authentication to an Axum service, when a login route must issue a bearer token, when handlers must require a valid token, or when migrating a JWT extractor from Axum 0.7 to 0.8. Prevents the hardcoded-secret security hole, the missing exp claim that makes every token fail to decode, implementing Claims as FromRequest instead of FromRequestParts, and leaking raw jsonwebtoken errors to the client. Covers the jsonwebtoken crate (v10, aws_lc_rs), the Claims struct, encode and decode, Validation::default, EncodingKey and DecodingKey from an env-var secret, the FromRequestParts extractor that makes any handler protected, the AuthError enum with IntoResponse, and the async_trait difference between 0.7 and 0.8. Keywords: axum jwt, jsonwebtoken, encode, decode, Claims, EncodingKey, DecodingKey, Validation, FromRequestParts, Authorization Bearer, JWT_SECRET, 401 unauthorized, InvalidToken, token expired, every token rejected, how do I protect a route, how do I add login to axum, what is a

Use when an Axum app must authenticate users with server-side sessions instead of self-contained tokens: a server-rendered web app with a login form, a flow that needs instant logout or revocation, mutable per-user state like a cart, HTTP Basic auth for an internal admin endpoint, or an OAuth2 social-login (Google, GitHub, corporate SSO) callback. Prevents shipping MemoryStore to production where sessions vanish on restart, prevents the with_secure(false) cookie leak over plain HTTP, prevents the session-fixation hole from not rotating the session id on login, prevents Basic auth credentials traveling in cleartext, prevents the OAuth2 login-CSRF hole from skipping the state check, and prevents login_required! applied with .layer() turning a 404 into an auth redirect. Covers the four-way auth decision tree (JWT vs session vs Basic vs OAuth2), tower-sessions SessionManagerLayer and the Session API, axum-login AuthSession with the AuthUser and AuthnBackend traits and the login_required! guard, axum-extra TypedHe

Use when an Axum app must decide whether an already-authenticated user is allowed to reach a route: protecting an /admin section, gating an endpoint behind a role, or enforcing a fine-grained permission like users:write. Prevents applying the guard with .layer() instead of .route_layer() (which turns a genuine 404 into a 401 and leaks which routes exist), prevents returning 401 on a failed authorization check when the answer is 403, prevents hardcoding a role hierarchy into every endpoint, prevents re-verifying the token inside a guard extractor, and prevents the wrong middleware argument order. Covers role-based and permission-based access control as from_fn and from_fn_with_state middleware applied with route_layer, the 401-versus-403 status rule, the layer-versus-route_layer decision, and the newtype guard extractor pattern (AdminClaims) with its FromRequestParts impl in both Axum 0.7 and 0.8 form. Keywords: axum authorization, RBAC, role-based access control, permission check, from_fn, from_fn_with_state,

Use when an Axum handler must accept a file upload or any multipart/form-data request: a browser form with an input type=file, an image or document upload, or a mixed form that carries text fields and a file together. Prevents the upload that works for tiny test files and then returns 413 on a real file, prevents a second body extractor placed after Multipart, prevents buffering a huge file into RAM, prevents a path-traversal hole from trusting the client-supplied file name, and prevents an unbounded request body DoS after calling disable(). Covers the multipart Cargo feature, the Multipart extractor and its FromRequest "must be last" rule, the next_field loop, Field metadata and body methods, buffering with bytes or text versus streaming with chunk to a tokio::fs::File, and the DefaultBodyLimit and RequestBodyLimitLayer body size ceiling. The Multipart API is identical in Axum 0.7 and 0.8. Keywords: axum file upload, Multipart, multipart form-data, next_field, Field, bytes, text, chunk, DefaultBodyLimit, Req

Use when an Axum handler must push a one-way server-to-client stream over plain HTTP: live notifications, log tailing, progress updates, an LLM token feed, or any "the browser only ever receives" channel consumed by an EventSource. Prevents the compile error from returning a bare Stream of Event instead of the required Result<Event, E> item type, prevents the dropped-connection bug from omitting KeepAlive on a quiet long-lived stream, prevents the runtime panic from calling a single-use Event builder method twice, and prevents reaching for WebSockets when the client never sends anything back. Covers axum::response::sse::Sse, Event, KeepAlive, the TryStream<Ok = Event> bound on Sse::new, the .map(Ok) infallible lift, the Event builder methods (.data, .json_data, .event, .id, .retry, .comment) with their documented panics, the json and tokio feature flags, and the SSE versus WebSocket decision. Keywords: axum SSE, server-sent events, axum::response::sse, Sse::new, Event, KeepAlive, EventSource, text/event-strea

Use when adding WebSocket endpoints to an Axum service, when migrating WebSocket code from Axum 0.7 to 0.8, or when a socket can receive client input but cannot push messages on its own schedule. Prevents the sequential-only echo trap, blocking the Tokio worker inside a socket task, the silent dropped upgrade failure, and the 0.7 to 0.8 Message payload-type break. Covers the ws cargo feature, WebSocketUpgrade, on_upgrade, on_failed_upgrade, the WebSocket connection, the Message enum, split plus tokio::spawn plus tokio::select, and combining the upgrade with State and ConnectInfo. Keywords: axum websocket, WebSocketUpgrade, on_upgrade, on_failed_upgrade, Message::Text, Utf8Bytes, Bytes, split sink stream, tokio::select, ws feature, server cannot push messages, websocket only echoes, connection freezes, Message::Text expects String, mismatched types String Utf8Bytes, how do I add websockets to axum, what is on_upgrade.

Use when adding middleware to an Axum service: a logging or timing layer, an auth gate, a header rewriter, or any cross-cutting code that must run before or after a handler with axum::middleware::from_fn, from_fn_with_state, map_request, or map_response. Prevents the wrong middleware argument order that triggers a "Handler is not satisfied" trait-bound error, the auth gate that turns a 404 into a 401 because it used layer instead of route_layer, the silently dropped handler from a from_fn that never calls next.run, and the reversed execution order from confusing stacked Router::layer with ServiceBuilder. Covers the axum::middleware helper family, the parts-then-Request-then-Next argument rule, the Next type and deliberate short-circuiting, layer ordering, the route_layer versus layer decision, and when to drop to a tower::Layer. Keywords: axum middleware, from_fn, from_fn_with_state, map_request, map_response, Next, next.run, route_layer, layer, tower Layer, middleware order, onion model, Handler is not satis

Use when an Axum app must serve static files: a CSS/JS/image assets directory, a single file on one route, or a single-page-app build where any unmatched path falls back to index.html. Prevents the trait-bound compile error from passing ServeDir to .layer() instead of mounting it as a route service, prevents the .fallback() versus .fallback_service() mix-up, prevents repeating the URL prefix inside the disk path, and prevents an SPA fallback that returns 200 for unknown URLs. Covers the tower-http fs and set-status feature flags, ServeDir and ServeFile as tower Services, .nest_service / .fallback_service / .route_service mounts, .not_found_service versus .fallback, SetStatus, and the canonical SPA fallback pattern. Keywords: axum static files, ServeDir, ServeFile, tower-http, nest_service, fallback_service, route_service, not_found_service, SetStatus, fs feature, set-status feature, serve a directory, serve index.html, SPA fallback, single page app routing, ServeDir is not a Layer, the trait bound Layer is no

Use when adding middleware to an Axum app through tower and tower-http: TraceLayer, CorsLayer, CompressionLayer, TimeoutLayer, RequestBodyLimitLayer, a ServiceBuilder stack, or rate limiting. Prevents the silent layer-reordering bug from confusing ServiceBuilder ordering (first added is outermost) with stacked Router::layer() ordering (last added is outermost), prevents shipping CorsLayer::permissive to production, prevents the cannot-find-layer compile error from a missing tower-http Cargo feature, and prevents expecting a tower-http rate-limit layer that does not exist. Covers the tower Service and Layer traits, the poll_ready backpressure contract, the ServiceBuilder ordering rule, the tower-http layer set with feature flags, CorsLayer configuration, and rate limiting via tower::limit and the tower_governor crate. Keywords: axum tower, tower Service trait, tower Layer trait, ServiceBuilder, poll_ready, tower-http, TraceLayer, CorsLayer, CompressionLayer, TimeoutLayer, RequestBodyLimitLayer, layer ordering,

Use when implementing a custom extractor in Axum: a type that builds itself from the request by implementing FromRequestParts or FromRequest, a wrapper that runs an inner extractor and remaps its rejection, or a struct derived with axum-macros #[derive(FromRequest)]. Prevents the stale 0.7 habit of keeping #[async_trait] on a 0.8 extractor impl, prevents the ambiguous-extractor bug from implementing both FromRequest and FromRequestParts for one concrete type, and prevents the "Handler is not satisfied" error from a body extractor that is not last. Covers the two extractor traits and the Rejection associated type, the FromRequestParts vs FromRequest choice, native async fn in trait versus #[async_trait], wrapping and remapping an inner extractor, FromRef substate access, and the axum-macros derive attributes. Keywords: axum custom extractor, FromRequestParts, FromRequest, impl FromRequestParts, type Rejection, IntoResponse, async_trait removal, RPITIT, derive FromRequest, from_request via, from_request rejecti

Use when writing or fixing an Axum handler function: deciding the argument list, the return type, or why a function is rejected as a handler. Prevents the "the trait bound Handler is not satisfied" error caused by a non-extractor argument, a body extractor that is not last, a return type that does not implement IntoResponse, a synchronous function, a non-Send future, or more than 16 arguments. Covers the Handler<T, S> trait and its blanket impl, the six eligibility criteria, valid return types including Result handlers, async closures as handlers, the 16-extractor limit, and serving one handler without a Router via HandlerWithoutStateExt::into_make_service. Keywords: axum handler, Handler trait, Handler<T, S>, blanket impl, IntoResponse return type, async fn handler, 16 argument limit, async closure handler, into_make_service, HandlerWithoutStateExt, debug_handler, Handler is not satisfied, trait bound is not satisfied, handler will not compile, function not accepted as handler, my route does not compile, how

Use when a handler must return a status code, headers, JSON, HTML, raw bytes, a redirect, or a cookie in Axum, or when a handler return value fails the Handler trait bound because the returned type does not implement IntoResponse. Prevents returning a bare domain struct or a bare integer that does not implement IntoResponse, prevents the wrong tuple order where the body is not the final element, prevents using 301 for a permanent redirect when Axum emits 308, and prevents a CookieJar silently dropping changes when the jar is not returned from the handler. Covers IntoResponse and IntoResponseParts, status and header and body tuple combining, Json and Html and raw byte bodies, Redirect (303, 307, 308), AppendHeaders, raw Set-Cookie headers, the axum-extra CookieJar family, and the Axum 0.8 axum::body::Body requirement. Keywords: axum IntoResponse, IntoResponseParts, ResponseParts, Json, Html, Form, Redirect, Redirect::to, Redirect::permanent, Redirect::temporary, AppendHeaders, NoContent, StatusCode, HeaderMap,

Use when an Axum service is slow under concurrent load, has high tail latency, freezes, or stops responding, and when a handler must run CPU-bound work, a blocking library call, or long-running background work. Prevents blocking the Tokio runtime, the !Send future trap that breaks the Handler trait bound, creating a database pool per request, and pool exhaustion that hangs requests instead of failing fast. Covers tokio::spawn versus tokio::task::spawn_blocking, the async I/O substitution table, !Send values held across .await, the tokio worker and blocking thread pools, runtime tuning, and connection pool sizing. Keywords: tokio::spawn, spawn_blocking, blocking the runtime, async performance, tokio::sync::Mutex, std::sync::MutexGuard not Send, JoinHandle, worker threads, max_blocking_threads, acquire_timeout, connection pool sizing, server slow under load, high tail latency, requests hang, app freezes, handler future is not Send, Handler is not satisfied, why is my axum server slow, how do I run blocking code

Use when upgrading an Axum project from 0.7 to 0.8, when an app that compiled on 0.7 now panics at startup or fails to compile after the version bump, or when deciding which path and extractor syntax a piece of Axum code targets. Prevents leaving 0.7 path syntax in place (a startup panic), keeping #[async_trait] on custom extractors (a compile error), relying on the old Option<Path<T>> swallow-all behavior, and calling APIs removed in 0.8. Covers the complete 0.7 to 0.8 breaking-change matrix, the path-syntax change, #[async_trait] removal and RPITIT, the WebSocket Message type change, the Option extractor change, the Sync bound, tuple Path arity, the removed-API checklist, and an ordered step-by-step migration checklist. Keywords: axum 0.7 to 0.8, axum upgrade, axum migration, breaking changes, matchit 0.8, path syntax panic, async_trait removed, RPITIT, OptionalFromRequest, Utf8Bytes, axum::Server removed, RawBody removed, TypedHeader moved, MSRV 1.75, app panics on startup after upgrade, code stopped compi

Use when a handler must read data from a request in Axum: path parameters, query strings, JSON or form bodies, headers, the method, or shared state. Prevents the "Handler is not satisfied" trait-bound error caused by a body extractor placed before another argument or by two body extractors in one handler, and prevents the 0.7-era assumption that Option<Path<T>> swallows every error. Covers the built-in extractor set, the FromRequestParts vs FromRequest classification, the body-extractor ordering rule, Path deserialization (single, tuple, struct, map), Json and Query behavior, and the 0.8 Option and Result wrapper semantics. Keywords: axum extractor, FromRequest, FromRequestParts, Path, Query, Json, Form, State, Extension, HeaderMap, Multipart, body extractor must be last, Handler is not satisfied, cannot consume body twice, 400 Bad Request path param, missing content-type json, Option Path swallows errors, how do I read a path parameter, parse the query string, get the request body, which extractor do I use.

Use when starting an Axum project, choosing Axum over another Rust web framework, explaining how Axum fits together, or debugging why a handler will not compile or a server process exits immediately. Prevents treating Axum as a monolith, adding a needless 0.7-vs-0.8 version split to the entry point, and chasing the cryptic "Handler is not satisfied" error without the #[debug_handler] macro. Covers the tokio plus hyper plus tower composition, the full request lifecycle, the no-macros design and its trade-off, axum::serve as the glue, the axum-core crate boundary, and the decision context for choosing Axum. Keywords: axum architecture, axum::serve, tokio hyper tower composition, request lifecycle, macro-free API, no macros, Handler is not satisfied, debug_handler, axum-core crate boundary, server exits immediately, main returns too soon, what is axum, how do I start an axum app, why will not my handler compile, #[tokio::main], how does axum work.

Use when defining routes, mounting sub-routers, or wiring middleware onto an Axum Router, especially when the server panics on startup with a routing message, returns 404 where 405 is expected, or runs middleware on only some routes. Prevents the 0.7 path-syntax startup panic, the double-fallback merge panic, the layer-registered-before-routes bug, and 404-versus-405 confusion. Covers Router<S>, .route, method-routers, .nest, .nest_service, .merge, .fallback, .method_not_allowed_fallback, .reset_fallback, .layer versus .route_layer, with_state, NestedPath, route precedence and overlap panics, and the 0.7 ":id" versus 0.8 "{id}" path-syntax change. Keywords: axum router, .route, .nest, .merge, method router, MethodRouter, 405 Method Not Allowed, 404 Not Found, route_layer, with_state, NestedPath, catch-all wildcard, overlaps with another route, server panics on startup, routes not matching, middleware not running on some routes, how do I add a route, what is nest versus merge, why does my axum app crash at sta

Use when wiring shared application state into an Axum service: database pools, configuration, caches, or any value handlers must reach through the State extractor. Prevents the runtime-500 Extension trap, the cryptic "Handler is not satisfied" error caused by a missing with_state call, and the non-Send handler future caused by holding a std::sync::Mutex guard across an .await point. Covers Router::with_state, the State extractor, the Router<S> typing model, FromRef substate composition, the derive(FromRef) macro, State vs Extension, the missing-state compile error, and std vs tokio Mutex for mutable shared state. Keywords: axum state, with_state, State extractor, FromRef, derive FromRef, substate composition, Router type parameter, Extension vs State, shared application state, AppState, Arc, tokio Mutex, std Mutex, trait bound Handler is not satisfied, missing state, expected Router unit type, 500 missing extension, how do I share a database pool, global config, app-wide cache, mutable shared state.