Handler trait not satisfied for some handlers despite identical signatures

[stephenway]

• I have looked for existing issues (including closed) about this

Bug Report

Version

axum v0.8.5
axum-core v0.5.5

Platform

Darwin 25.0.0 (macOS)

Crates

• axum (0.8.5)
• axum-core (0.5.5)

Description

Short summary: Some handlers with identical signatures to working handlers fail to satisfy the Handler trait in Axum 0.8.5, causing compilation errors. The issue also occurs in Axum 0.7.9, suggesting it's not version-specific.

I tried this code:

// Working handler (compiles successfully)
// In handlers/module_a.rs
pub async fn create_resource_a(
    State(state): State<crate::AppState>,
    Json(request): Json<CreateResourceARequest>,
) -> Result<Json<ApiResponse<ResourceAResponse>>, Error> {
    // ... implementation
}

// In server.rs
.route("/api/v1/resources-a", post(create_resource_a).get(list_resources_a))

// Failing handler (identical signature, fails to compile)
// In handlers/module_b.rs
pub async fn create_resource_b(
    State(state): State<crate::AppState>,
    Json(request): Json<CreateResourceBRequest>,
) -> Result<Json<ApiResponse<ResourceBResponse>>, Error> {
    // ... implementation
}

// In server.rs
.route("/api/v1/resources-b", post(create_resource_b).get(list_resources_b))

I expected to see this happen: Both handlers should compile successfully since they have identical function signatures and follow the same pattern.

Instead, this happened: The second handler fails with:

error[E0277]: the trait bound `fn(State<AppState>, Json<...>) -> ... {create_resource_b}: Handler<_, _>` is not satisfied
   --> src/server.rs:XX:XX
    |
 XX |         .route("/api/v1/resources-b", post(create_resource_b))
    |                                    ---- ^^^^^^^^^^^^^^^^^ unsatisfied trait bound
    |
    = help: the trait `Handler<_, _>` is not implemented for fn item `fn(State<AppState>, Json<CreateResourceBRequest>) -> ... {create_resource_b}`

Additional observations:

1. Other handlers in the same module work: Other handlers in module_b.rs work correctly:

   • Handlers with only State extractor work
   • Handlers with State + Path work
   • Handlers with State + Extension + Json work
   • Handlers with State + Path + Json work

2. Pattern in failing handlers:

   • Handlers with State + Json (POST with body) fail
   • Handlers with State + Path (DELETE) fail
   • All failing handlers are in the same module

3. Request type differences: The failing handlers use request types that may contain:

   • Option<serde_json::Value>
   • Nested structs
   • Multiple Option fields

Request/Response Types:

// Working handler request type
#[derive(Debug, Deserialize)]
pub struct CreateResourceARequest {
    pub name: String,
    pub items: Vec<Item>,
    pub metadata: HashMap<String, String>,
}

// Failing handler request type
#[derive(Debug, Deserialize)]
pub struct CreateResourceBRequest {
    pub id: Option<String>,
    pub name: String,
    pub description: Option<String>,
    pub nested: Option<NestedRequest>,
    pub json_data: Option<serde_json::Value>,
    pub tags: Option<Vec<String>>,
}

Attempted workarounds (all failed):

1. Using State<AppState> with use crate::state::AppState; (same as working handlers)
2. Using State<crate::AppState> (same as working handlers)
3. Wrapper functions with explicit type annotations
4. Using closures with explicit types
5. Using MethodRouter directly
6. Separating routes (.route().route() instead of chaining)
7. Ensuring router function signature matches handler types
8. Matching exact import patterns from working handlers
9. Type aliases (pub type AppStateAlias = crate::AppState)
10. Testing on separate routes (not route-specific)
11. Downgrading to Axum 0.7.9 (same errors occur)

Environment:

• Rust version: 1.91.1 (also occurs with 1.90.0)
• Axum version: 0.8.5 (also occurs with 0.7.9)

Questions:

1. Is there something specific about certain handler signature combinations that prevents type inference?
2. Could this be related to request/response types containing Option<serde_json::Value> or nested structs?
3. Is there a known issue with Handler trait inference?
4. Why do some handlers in the same module work while others with identical patterns fail?

[yanns]

Have you tried the #[debug_handler] macro that should give better compilation errors?
https://docs.rs/axum/latest/axum/attr.debug_handler.html

[stephenway]

Thanks, that's what I needed!

[jplatte]

If it's not the signature, your async fn returns a Future that is not Send. In addition to the macro @yanns linked, there is also a clippy lint for finding out why that is: https://rust-lang.github.io/rust-clippy/master/index.html?search=Future#future_not_send

You may have to comment out the problematic route calls to get rid of the compiler error when enabling this lint to see it trigger.

[stephenway]

Great tip, thanks!