HTTP/1.1 431 Request Header Fields Too Large from Kestrel means the request's
headers together were bigger than the server accepts. In this test a single 40,000-byte
Cookie line was enough. Make the headers smaller, or raise
MaxRequestHeadersTotalSize in the Kestrel limits.
Raising the limit to 64 KB with ConfigureKestrel turned the same request
into a 200. Shrinking the header is the better fix when you control it, because then
the default limit can stay as it is.
The error
The header line was kept in a file and sent with curl's -H "@file" form. The
response had no body and closed the connection; the server console printed nothing at
the template's default log levels:
PS> (Get-Item bigheader.txt).Length
40017
PS> curl.exe -s -i -H "@bigheader.txt" http://127.0.0.1:15630/
HTTP/1.1 431 Request Header Fields Too Large
Content-Length: 0
Connection: close
Date: Sat, 14 Nov 2026 01:17:44 GMT
Server: Kestrel
Why it happens
The header file was written in PowerShell and checked like this:
PS> [IO.File]::WriteAllText("$az\bigheader.txt", "Cookie: session=" + ('a' * 40000) + "`n")
PS> (Get-Content bigheader.txt -Raw).Substring(0, 40)
Cookie: session=aaaaaaaaaaaaaaaaaaaaaaaa
PS> (Get-Content bigheader.txt).Count
1
So the file held one line, Cookie: session= followed by 40,000 letters
a, and the request's header block was over 40,000 bytes. The app itself was
the template's one-endpoint API with no limits set. The 431 response carried
Server: Kestrel, no body and Connection: close, so it was the
server's own answer, not a page the app wrote. The test used one oversized
Cookie line; any header that pushes the total over the limit is worth
checking the same way.
Before you change a limit, find out which header is large: measure what the client really sends rather than guessing. Here the file length printed by PowerShell gave the number directly, and raising the limit above it was enough.
The fix
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(options =>
{
options.Limits.MaxRequestHeadersTotalSize = 64 * 1024;
});
var app = builder.Build();
app.MapGet("/", () => "Clinic API is running");
app.Run();
PS> curl.exe -s -i -H "@bigheader.txt" http://127.0.0.1:15630/
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Sat, 14 Nov 2026 01:17:47 GMT
Server: Kestrel
Transfer-Encoding: chunked
Clinic API is running
Raise the limit only as far as the largest real header needs. This test ran Kestrel with no proxy in front of it; if your app sits behind one, test the same oversized request through it too. When the header is a cookie you control, keep less in it.
How it was reproduced
A minimal API made with dotnet new web -f net10.0 on SDK 11.0.100, running on
Microsoft.AspNetCore.App 10.0.15 in the Production environment, built and started by a small script, start.ps1, which runs dotnet build -nologo -v q in the project folder and then bin\Debug\net10.0\FixLab.exe --urls http://127.0.0.1:15630, Kestrel directly with no proxy.
The 40,017-byte header file was written by PowerShell and sent with
curl.exe -s -i -H "@bigheader.txt", before and after setting
MaxRequestHeadersTotalSize.
Frequently asked
- What does 431 Request Header Fields Too Large mean in ASP.NET Core?
- Kestrel refused the request because its headers together were larger than its limit. In the test one 40,000-byte Cookie header produced 431 with an empty body and Connection: close.
- How do I increase the request header size limit in Kestrel?
- Set options.Limits.MaxRequestHeadersTotalSize inside builder.WebHost.ConfigureKestrel. In the test 64 * 1024 let the same 40,000-byte header through with a 200.
- Is it better to raise the Kestrel header limit or shrink the cookie?
- Shrinking the header lets the default limit stay. If you raise the limit, raise it only as far as the largest real header needs; in the test 64 KB was enough for a 40,000-byte header.
More decoded errors in the Fixes category.