Skip to content
  • Home
  • About
  • No Access
  • Privacy Policy
Bits of .NET
Bits of .NET
  • Asp.Net Core
  • C#
  • SQL
  • JavaScript
  • CSS
  • About
  • ErcanOPAK.com
  • No Access
  • Privacy Policy

Bits of .NET

Daily micro-tips for C#, SQL, performance, and scalable backend engineering.

  • Asp.Net Core
  • C#
  • SQL
  • JavaScript
  • CSS
  • About
  • ErcanOPAK.com
  • No Access
  • Privacy Policy
Asp.Net Core

ASP.NET Core: Fix a Minimal API Request That Matches the Wrong Handler Because Two Routes Differ Only by a Trailing Optional Parameter

- 28.10.26 - ErcanOPAK

⚙️ Fix a Minimal API Request That Matches the Wrong Handler Because Two Routes Differ Only by a Trailing Optional Parameter

ASP.NET Core’s routing engine picks the best match among all registered routes for a given request path, and when two minimal API routes differ only by a trailing optional segment, a request that could satisfy either one doesn’t always resolve to the route you’d intuitively expect – the more specific route should win by routing’s own precedence rules, but a subtly different parameter constraint or ordering of app.MapGet calls can flip which handler actually executes, with no routing conflict error raised at startup to warn you.

🔎 The Problem

app.MapGet("/orders/{id}", (int id) =>
    Results.Ok($"single order {id}"));

app.MapGet("/orders/{id?}", (int? id) =>
    Results.Ok(id is null ? "all orders" : $"order {id}"));

// GET /orders/42
// Expected: the first, more specific handler.
// Actual: depends on registration order and exact route
// template matching rules - the optional-parameter route
// can end up matching requests the required-parameter
// route was clearly meant to own, with no startup error
// indicating the two routes overlap at all.

✅ Fix: Make Route Specificity Explicit Instead of Relying on Registration Order

  • Avoid registering a required-parameter route and an optional-parameter version of the same path together – collapse them into one handler that treats the parameter as nullable internally, which removes the ambiguity entirely instead of relying on routing precedence to resolve it correctly.
  • If two similar routes genuinely need to stay separate, give them distinct path segments (/orders/{id} versus /orders/search) rather than letting an optional trailing parameter be the only thing that tells them apart.
  • Log the actual matched endpoint for a request during testing (app.Use middleware that reads HttpContext.GetEndpoint()) to directly confirm which handler is executing, rather than inferring it only from the response body – two handlers that both happen to return similar-looking JSON can mask a routing mismatch for a long time.

🚨 Why This Is Dangerous

  • Because no startup-time error flags this kind of overlapping route pair, the wrong handler can run silently in production for a specific path shape that testing happened not to exercise, and it surfaces only when a particular ID value or request pattern finally triggers the ambiguous case.

Two routes that look unambiguous to you can still look ambiguous to the router – and the router, not your intent, is what decides which handler actually runs.

— Backend Architect

Related posts:

ASP.NET Core: Why Adding a New Migration Doesn't Update Your Database Automatically

ASP.NET Core: Why Adding a New Migration Doesn't Update Your Database Automatically

C# Records — Why They Still Beat Classes for Domain Models

C# Records — Why They Still Beat Classes for Domain Models

.NET Core — Thread Pool Starvation Looks Like CPU Idle

.NET Core — Thread Pool Starvation Looks Like CPU Idle

Views: 7

Post navigation

Git: Fix a Merge Reporting Already Up to Date Even Though the Remote Has New Commits Because You Forgot to Fetch First
Windows 11: Fix Clipboard Copy-Paste Between a Remote Desktop Session and the Local Machine Silently Stopping After the Session Sits Idle for a While

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

November 2026
M T W T F S S
 1
2345678
9101112131415
16171819202122
23242526272829
30  
« Oct    

Most Viewed Posts

  • How to make theater mode the default for Youtube (1,055)
  • Get the User Name and Domain Name from an Email Address in SQL (980)
  • How to add default value for Entity Framework migrations for DateTime and Bool (977)
  • Get the First and Last Word from a String or Sentence in SQL (857)
  • How to select distinct rows in a datatable in C# (854)
  • How to enable, disable and check if Service Broker is enabled on a database in SQL Server (653)
  • Add Constraint to SQL Table to ensure email contains @ (609)
  • Average of all values in a column that are not zero in SQL (570)
  • How to use Map Mode for Vertical Scroll Mode in Visual Studio (546)
  • Find numbers with more than two decimal places in SQL (475)

Recent Posts

  • C#: Fix a ConditionalWeakTable Entry Vanishing Too Soon
  • Docker: Fix a Stale COPY Layer After Editing .dockerignore
  • Photoshop: Fix a Pattern Overlay Scaling Wrong on a High-DPI File
  • SQL Server: Fix a Computed Column Index Skipped by Implicit Cast
  • HTML5: Fix a required Input Inside a Hidden Tab Blocking Submit
  • SQL Server: Fix ROW_NUMBER Ties Reordering Between Identical Runs
  • C#: Fix an Enum HasFlag Returning True for the Zero Value
  • WordPress: Fix Featured Images Vanishing After a CDN Migration
  • Photoshop: Fix Content-Aware Fill Smearing a Repeating Pattern
  • Asp.Net Core: Fix Antiforgery Tokens Rejected Behind a Reverse Proxy

Most Viewed Posts

  • How to make theater mode the default for Youtube (1,055)
  • Get the User Name and Domain Name from an Email Address in SQL (980)
  • How to add default value for Entity Framework migrations for DateTime and Bool (977)
  • Get the First and Last Word from a String or Sentence in SQL (857)
  • How to select distinct rows in a datatable in C# (854)

Recent Posts

  • C#: Fix a ConditionalWeakTable Entry Vanishing Too Soon
  • Docker: Fix a Stale COPY Layer After Editing .dockerignore
  • Photoshop: Fix a Pattern Overlay Scaling Wrong on a High-DPI File
  • SQL Server: Fix a Computed Column Index Skipped by Implicit Cast
  • HTML5: Fix a required Input Inside a Hidden Tab Blocking Submit

Social

  • ErcanOPAK.com
  • GoodReads
  • LetterBoxD
  • Linkedin
  • The Blog
  • Twitter
© 2026 Bits of .NET | Built with Xblog Plus free WordPress theme by wpthemespace.com