An unhandled exception has occurred while executing the request.
Codul unui endpoint a aruncat o excepție pe care nu a prins-o nimeni, așa că ASP.NET Core a răspuns 500 Internal Server Error și a scris acest mesaj în log, urmat de excepția reală. Citește excepția de sub mesaj și tratează cazul în handler (de exemplu 404 pentru o resursă lipsă).
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Mesajul este logul scris de middleware-ul de erori (DeveloperExceptionPageMiddleware în Development, ExceptionHandlerMiddleware în Production), la nivelul fail, când o excepție ajunge până la el. Nu e cauza, ci anunțul: excepția reală e imediat dedesubt, cu tipul, mesajul și stack trace-ul (de exemplu System.Collections.Generic.KeyNotFoundException: The given key '5' was not present in the dictionary.).
Clientul primește 500. În Development, corpul răspunsului este pagina de excepție pentru dezvoltator (în laborator, primul rând al ei: tipul și mesajul excepției); în Production, un răspuns gol sau un ProblemDetails generic, ca să nu scurgi detalii interne.
Ce faci: citești tipul excepției și prima linie din stack trace care aparține codului tău. Situațiile previzibile (resursă inexistentă, date invalide, conflict) nu trebuie să ajungă excepții neprinse: le tratezi în handler cu 404, 400 sau 409.
De ce apare: cauzele frecvente
1Acces la o cheie care nu există
app.MapGet("/produse/{id:int}", (int id) => produse[id]);app.MapGet("/produse/{id:int}", (int id) =>
produse.TryGetValue(id, out var p) ? Results.Ok(p) : Results.NotFound());Indexerul dicționarului aruncă KeyNotFoundException; TryGetValue îți permite să răspunzi 404.
2null tratat ca obiect
var client = clienti.FirstOrDefault(c => c.Id == id);
return client.Nume;var client = clienti.FirstOrDefault(c => c.Id == id);
return client is null ? Results.NotFound() : Results.Ok(client.Nume);FirstOrDefault întoarce null când nu găsește nimic; accesul la .Nume dă NullReferenceException și 500.
3Excepție de business lăsată să urce
if (stoc < cantitate) throw new InvalidOperationException("Stoc insuficient");if (stoc < cantitate) return Results.Conflict("Stoc insuficient");O regulă de business încălcată e un răspuns normal pentru client (409), nu o eroare de server.
Repară eroarea, direct în pagină
GET /produse/5 răspunde 500: handler-ul citește din dicționar cu indexerul, iar produsul 5 nu există (KeyNotFoundException). Repară handler-ul ca să răspundă 200 cu numele produsului când există și 404 cu mesajul Produsul 5 nu există când lipsește.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var produse = new Dictionary<int, string> { [1] = "Laptop", [2] = "Mouse" };
app.MapGet("/produse/{id:int}", (int id) => produse[id]);
app.Run();GET /produse/1 → 200 OK "Laptop" GET /produse/5 → 404 Not Found "Produsul 5 nu există"
Indiciu
TryGetValue întoarce false în loc să arunce.
Reparația
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var produse = new Dictionary<int, string> { [1] = "Laptop", [2] = "Mouse" };
app.MapGet("/produse/{id:int}", (int id) =>
produse.TryGetValue(id, out var nume)
? Results.Ok(nume)
: Results.NotFound($"Produsul {id} nu există"));
app.Run();De ce merge
Indexerul produse[id] aruncă KeyNotFoundException pentru o cheie lipsă, iar excepția neprinsă devine 500. Un produs inexistent e un caz normal, nu o eroare de server: TryGetValue verifică fără excepție, iar Results.NotFound spune clientului exact ce s-a întâmplat. Excepțiile rămân pentru situațiile cu adevărat neprevăzute.
Alte forme ale mesajului
fail: Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware[1] An unhandled exception has occurred while executing the request.fail: Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware[1] An unhandled exception has occurred while executing the request.fail: Microsoft.AspNetCore.Server.Kestrel[13] Connection id "0HN1", Request id "0HN1:00000001": An unhandled exception was thrown by the application.
Cum o eviți pe viitor
- Tratează în handler cazurile previzibile:
TryGetValue, verificări denull,Results.NotFound/BadRequest/Conflict. - Configurează în producție
UseExceptionHandler+AddProblemDetails, ca erorile neprevăzute să aibă un răspuns standard. - Loghează cu context (id-ul cererii, utilizatorul) ca să poți reproduce problema.
- Scrie un test pentru fiecare 500 găsit, înainte să-l repari.
Întrebări frecvente
De ce local văd detaliile, iar pe server doar 500?
În Development, pagina pentru dezvoltator afișează excepția în răspuns. În Production, detaliile apar doar în loguri, pentru că ar expune informații interne. Caută în logurile serverului linia cu acest mesaj.
Trebuie să pun try/catch în fiecare endpoint?
Nu. Tratezi explicit cazurile previzibile, iar restul le lași middleware-ului global (UseExceptionHandler sau un IExceptionHandler), care loghează și întoarce un răspuns standard.
Erori înrudite
{"type":"https://tools.ietf.org/html/rfc9110#section-15.6.1","title":"An error occurred while processing your request.","status":500} Este răspunsul ProblemDetails generic pe care UseExceptionHandler cu AddProblemDetails îl trimite pentru orice excepție neprinsă. Detaliile sunt doar în log. Dacă excepția corespunde unui caz cunoscut (stoc insuficient, resursă lipsă), mapeaz-o la codul potrivit cu un IExceptionHandler. System.InvalidOperationException: An error occurred when configuring the exception handler middleware. Either the 'ExceptionHandlingPath' or the 'ExceptionHandler' property must be set in 'UseExceptionHandler()'. Alternatively, set one of the aforementioned properties in 'Startup.ConfigureServices' as follows: 'services.AddExceptionHandler(options => { ... });' or configure to generate a 'ProblemDetails' response in 'service.AddProblemDetails()'. Ai apelat app.UseExceptionHandler() fără argumente, dar middleware-ul nu știe ce să răspundă la o excepție: nu are o cale, nici un delegat și nici AddProblemDetails. Adaugă builder.Services.AddProblemDetails() sau dă o cale: app.UseExceptionHandler("/eroare"). System.InvalidOperationException: The exception handler configured on ExceptionHandlerOptions produced a 404 status response. This InvalidOperationException containing the original exception was thrown since this is often due to a misconfigured ExceptionHandlingPath. If the exception handler is expected to return 404 status responses then set AllowStatusCode404Response to true. Ai configurat UseExceptionHandler("/eroare"), dar la calea /eroare nu există niciun endpoint, așa că re-executarea cererii a dat 404. Adaugă endpoint-ul de eroare (de exemplu app.Map("/eroare", ...) care întoarce Results.Problem) sau folosește AddProblemDetails cu UseExceptionHandler(). Învață ASP.NET Core de la zero, cu exerciții la fiecare lecție
Curs ASP.NET Core: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 20 lecții sunt gratuite.
