Why Your Minimal API Won't Compile: Solving the RequestDelegate Arguments Mystery

The Compiler Error That Stops You Cold

Picture this: You're building a sleek new minimal API in .NET, feeling productive with the streamlined syntax. You've embraced TypedResults to get better OpenAPI documentation (good practice!), but suddenly the compiler hits you with this cryptic message:

"The delegate 'RequestDelegate' does not take X arguments."

If you've been there, you know the frustration. The error message doesn't point you toward a solution, and your code looks perfectly fine. I've hit this exact wall multiple times, and I want to share what's actually happening and how to fix it properly.

What's Really Going On?

Minimal APIs in .NET are fantastic for their simplicity, but they hide some complexity under the hood. When you define an endpoint, the framework needs to figure out how to map your handler method to the underlying RequestDelegate that ASP.NET Core expects.

The problem surfaces when you use TypedResults (like TypedResults.Ok(), TypedResults.NotFound(), etc.) in your handlers. Here's where it gets interesting: the compiler struggles to infer the complete signature of your endpoint, especially when you have multiple possible return types. Without explicit type information, the delegate mapping fails, and you get that unhelpful error message.

In my experience building healthcare APIs where OpenAPI documentation is critical for integration partners, this issue appears most often in endpoints that return different status codes based on business logic - exactly where you need clear documentation the most.

The Solution: Results<T1, T2, ...>

The fix is actually elegant once you understand it. Instead of letting the compiler guess, you explicitly declare all possible return types using the generic Results<> type:

// Before - This might cause the RequestDelegate error
app.MapGet("/patients/{id}", async (int id, IPatientService service) =>
{
    var patient = await service.GetPatientAsync(id);
    if (patient == null)
        return TypedResults.NotFound();
    
    return TypedResults.Ok(patient);
});

// After - Explicit return type declaration
app.MapGet("/patients/{id}", async Task<Results<Ok<Patient>, NotFound>> 
    (int id, IPatientService service) =>
{
    var patient = await service.GetPatientAsync(id);
    if (patient == null)
        return TypedResults.NotFound();
    
    return TypedResults.Ok(patient);
})
.WithName("GetPatient")
.WithOpenApi();

Notice the Results<Ok<Patient>, NotFound> return type. You're telling the compiler: "This endpoint returns either an Ok with a Patient object, or a NotFound response." Problem solved.

The OpenAPI Bonus

Here's the part I really appreciate: This isn't just a compiler workaround. By being explicit about return types, your OpenAPI documentation becomes significantly better. The generated spec will show all possible response codes and their schemas.

For complex endpoints, you might have:

app.MapPost("/appointments", 
    async Task<Results<Created<Appointment>, BadRequest<ValidationErrors>, Conflict>> 
    (CreateAppointmentRequest request, IAppointmentService service) =>
{
    // Your implementation here
})
.WithOpenApi();

Now your API consumers can see at a glance that this endpoint might return 201 Created, 400 Bad Request with validation details, or 409 Conflict. That's documentation that actually helps.

Lessons from the Trenches

1. Be Explicit Early: Don't wait for the compiler error. Start with Results<> from the beginning when building minimal APIs. It saves debugging time and improves your API documentation in one shot.

2. Limit Return Type Combinations: If you find yourself declaring Results<T1, T2, T3, T4, T5, T6>, that's a code smell. Your endpoint might be doing too much. Consider splitting it or rethinking the design.

3. Create Type Aliases for Common Patterns: In our codebase, we define common result combinations:

public static class ApiResults
{
    public static Results<Ok<T>, NotFound, BadRequest<ValidationErrors>> 
        StandardGetResult<T>() => default!;
}

This keeps endpoint definitions clean and consistent.

The Bottom Line

Minimal APIs are powerful, but they require understanding what's happening beneath the simple syntax. When you hit the "RequestDelegate does not take X arguments" error, remember: the compiler needs your help to understand the complete signature of your endpoint.

Use Results<> to explicitly declare return types. Your code will compile, your OpenAPI docs will shine, and future you (or your teammates) will appreciate the clarity.

Action item: Go review your minimal APIs right now. Add explicit Results<> return types to any endpoint using TypedResults, even if it compiles today. Your documentation will thank you, and you'll avoid mysterious compiler errors down the road.

Have you encountered this error in your projects? I'd love to hear how you solved it or what patterns you've adopted for minimal API development. The .NET ecosystem keeps evolving, and sharing these practical solutions helps everyone build better APIs.