Bits of .NET

⚙️ Custom Middleware Crashing With No Clear Reason?

Custom middleware that tries to modify response headers or status codes AFTER the response body has started writing throws InvalidOperationException: Headers are read-only, response has already started — a timing bug that’s easy to introduce and confusing to diagnose from the exception message alone.

🐞 The Problem

public class ErrorHandlingMiddleware
{
    private readonly RequestDelegate _next;
    public ErrorHandlingMiddleware(RequestDelegate next) => _next = next;

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context); // downstream middleware already wrote to the response
        }
        catch (Exception ex)
        {
            context.Response.StatusCode = 500; // throws: response already started
            await context.Response.WriteAsync("An error occurred.");
        }
    }
}

🔍 Why This Happens

Once ANY bytes of the response body have been written to the
underlying network stream, the status code and headers are locked
- HTTP fundamentally requires headers to be sent before the body,
so ASP.NET Core can't quietly rewrite them after the fact. If a
downstream middleware/action already streamed part of a response
before throwing, your catch block's attempt to set StatusCode = 500
comes too late.

✅ The Fix: Check HasStarted Before Modifying the Response

• If the response has already started, you can no longer change the status code or headers — the best you can do is log it and let the connection close as-is.
• For a reliable global error page, put this middleware as early as possible in the pipeline (first, or very close to it) so less code runs before it can catch things.

🛡️ Defensive Version

public async Task InvokeAsync(HttpContext context)
{
    try
    {
        await _next(context);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Unhandled exception");

        if (!context.Response.HasStarted)
        {
            context.Response.Clear();
            context.Response.StatusCode = 500;
            await context.Response.WriteAsync("An error occurred.");
        }
        else
        {
            // Can't modify the response anymore - the best option
            // left is to log it and rethrow so the host logs it too.
            throw;
        }
    }
}

⚠️ Also Use the Built-In Exception Handler

• app.UseExceptionHandler(“/error”) (registered early in Program.cs) handles most of this correctly out of the box — only write custom middleware when you need behavior it doesn’t provide.