...
Eroare ASP.NET Core · Middleware, pipeline și excepții

{"type":"https://tools.ietf.org/html/rfc9110#section-15.6.1","title":"An error occurred while processing your request.","status":500}

Pe scurt

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.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

În producție, app.UseExceptionHandler() împreună cu builder.Services.AddProblemDetails() transformă orice excepție neprinsă într-un răspuns standard RFC 9110, cu Content-Type: application/problem+json: type (link spre secțiunea 500 din specificație), title An error occurred while processing your request. și status 500. În aplicația reală mai apare și un traceId, cu care găsești cererea în loguri.

Răspunsul e intenționat vag: nu trimite clientului mesajul excepției, care poate conține date interne. Cauza reală e în log, la nivelul fail.

Dacă vezi acest răspuns pentru situații obișnuite (comandă cu stoc insuficient, entitate inexistentă), înseamnă că le semnalezi cu excepții pe care nu le tratează nimeni. Din .NET 8, IExceptionHandler îți permite să transformi excepțiile de business în 404, 409 sau 422, cu un ProblemDetails clar, iar restul să rămână 500.

De ce apare: cauzele frecvente

1Excepție de business netratată

Greșit
C#
app.MapPost("/comenzi", () =>
{
    throw new StocInsuficientException("Stoc insuficient pentru Mouse");
});
Corect
C#
builder.Services.AddExceptionHandler<HandlerStoc>();
// HandlerStoc : IExceptionHandler -> 409 cu ProblemDetails

Excepția devine un 409 cu detalii utile pentru client, în loc de 500 generic.

2Te aștepți să vezi mesajul excepției în răspuns

Greșit
C#
// în Production, corpul nu conține mesajul excepției
Corect
C#
app.Logger.LogError(...); // sau citește logurile aplicației
// mesajul tehnic nu trebuie trimis clientului

Detaliile tehnice stau în loguri. În răspuns pui doar ce e sigur și util pentru client.

Repară tu

Repară eroarea, direct în pagină

În Production, POST /comenzi răspunde cu ProblemDetails 500 generic, deși cauza e cunoscută: StocInsuficientException. Scrie un IExceptionHandler care transformă această excepție în 409 cu ProblemDetails (title Stoc insuficient, detail = mesajul excepției) și înregistrează-l cu AddExceptionHandler.

Codul care dă eroarea
C#
using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
// TODO: înregistrează HandlerStoc
var app = builder.Build();
app.UseExceptionHandler();

app.MapPost("/comenzi", () =>
{
    throw new StocInsuficientException("Stoc insuficient pentru Mouse: cerut 5, disponibil 2");
});

app.Run();

public class StocInsuficientException(string mesaj) : Exception(mesaj);

public class HandlerStoc : IExceptionHandler
{
    public ValueTask<bool> TryHandleAsync(HttpContext ctx, Exception ex, CancellationToken token)
    {
        // TODO: 409 + ProblemDetails pentru StocInsuficientException, false pentru restul
        return ValueTask.FromResult(false);
    }
}
După reparație, programul afișează
POST /comenzi → 409 Conflict
{"title":"Stoc insuficient","status":409,"detail":"Stoc insuficient pentru Mouse: cerut 5, disponibil 2"}
Indiciu

TryHandleAsync întoarce false pentru alte excepții, ca ele să rămână 500.

Alte forme ale mesajului

  • {"type":"https://tools.ietf.org/html/rfc9110#section-15.6.1","title":"An error occurred while processing your request.","status":500,"traceId":"00-4f3a...-01"}

Cum o eviți pe viitor

  • Folosește excepții doar pentru situații neprevăzute; pentru cazuri de business, întoarce rezultate (Results.Conflict, Results.NotFound).
  • Când ai deja excepții de domeniu, mapează-le central cu IExceptionHandler.
  • Loghează excepțiile o singură dată, în handler-ul global.
  • Include traceId în răspuns (implicit în aplicația reală) ca suportul să poată găsi logul.

Întrebări frecvente

De unde vine traceId?

AddProblemDetails adaugă automat id-ul cererii (Activity.Current?.Id sau HttpContext.TraceIdentifier). În loguri cauți exact acel id.

Pot pune mesajul excepției în detail?

În Development e util, iar AddProblemDetails poate face asta prin CustomizeProblemDetails. În producție, nu: mesajele excepțiilor pot conține SQL, căi de fișiere sau date personale.

Erori înrudite

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ă). 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().

← Toate erorile ASP.NET Core

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.