skip to content

Why does a 150 MB upload to an ASP.NET Core 10 controller fail, and how do you raise the limits for that one action?

level: middleimportance: should knowfreq 50%

answer

  1. two independent limits
  2. server body cap: 30,000,000 bytes
  3. FormOptions.MultipartBodyLengthLimit: 128 MB per section
  4. [RequestSizeLimit] and [RequestFormLimits]
  5. "Failed to read the request form"

basics

~10 s

Two limits apply: the server's request body cap (Kestrel's default is 30,000,000 bytes) and FormOptions.MultipartBodyLengthLimit (128 MB per multipart section). Raise both for one action with [RequestSizeLimit(bytes)] and [RequestFormLimits(MultipartBodyLengthLimit = bytes)].

solid answer

~40 s

A 150 MB scan meets two separate checks. First, the server's maximum request body size: Kestrel's default is 30,000,000 bytes (about 28.6 MB), and IIS has its own `maxAllowedContentLength` of the same value. `[RequestSizeLimit(bytes)]` or `[DisableRequestSizeLimit]` on the action changes the server limit for that endpoint through `IHttpMaxRequestBodySizeFeature`. Second, form parsing: `FormOptions.MultipartBodyLengthLimit` is 128 MB for each multipart section, raised per action with `[RequestFormLimits(MultipartBodyLengthLimit = ...)]`, or globally with `Configure<FormOptions>`. When an `[ApiController]` action binds `IFormFile`, either failure is caught while the form is read and becomes a 400 whose `ModelState` error starts with "Failed to read the request form."; where nothing catches it, the server's own rejection is a 413. Raise only the endpoints that need it.

code

csharp · 13 lines
csharp
// global form defaults (all endpoints)
builder.Services.Configure<FormOptions>(o =>
    o.MultipartBodyLengthLimit = 64 * 1024 * 1024);

// one Minimal API endpoint: both limits raised
app.MapPost("/api/records/minimal",
        [RequestSizeLimit(220_000_000)] async (IFormFile scan, CancellationToken ct) =>
        {
            // save scan ...
            return TypedResults.Ok();
        })
   .WithFormOptions(multipartBodyLengthLimit: 209_715_200)
   .DisableAntiforgery(); // only if the caller is not a browser form

go deeper

for a junior

Recall that uploads have a server body limit around 28.6 MB and a 128 MB form limit, and that attributes raise them per action.

for a middle

Explain which component enforces each limit, that the form limit is per section, and why an [ApiController] reports a 400 instead of a 413.

for a senior

Set limits per endpoint with headroom, account for IIS and middleware that read the body early, and decide when buffering should give way to streaming.

for a principal

Set the organisation's upload envelope (sizes, endpoints, hosting layers) so that limits are deliberate rather than discovered in production.

## Two limits, checked by different components The telehealth app accepts scanned medical records of up to 200 MB. A 150 MB upload to a default controller fails, and raising one limit is not enough, because two components enforce two different caps: | Limit | Owner | Default | Scope | Per-endpoint override | |---|---|---|---|---| | Maximum request body size | the server (Kestrel, or IIS in-process) | 30,000,000 bytes (about 28.6 MB) | whole request body | `[RequestSizeLimit(bytes)]`, `[DisableRequestSizeLimit]` | | `FormOptions.MultipartBodyLengthLimit` | form parsing (`IFormFile` binding) | 134,217,728 bytes (128 MB) | **each** multipart section | `[RequestFormLimits(MultipartBodyLengthLimit = bytes)]` | A 150 MB file exceeds both. A 50 MB file exceeds only the server limit, which surprises people who raised `FormOptions` and nothing else. ## Raising the server limit for one action `[RequestSizeLimit(220_000_000)]` sets `IHttpMaxRequestBodySizeFeature.MaxRequestBodySize` for that request. The attribute is endpoint metadata (`IRequestSizeLimitMetadata`), so the routing middleware applies it after matching, for controllers and also for a Minimal API endpoint that carries the attribute. Two caveats: - The feature becomes read-only once the body has started to be read; a middleware that buffers the body earlier locks in the old limit. - On IIS, `maxAllowedContentLength` in `web.config` is checked by IIS itself, before ASP.NET Core sees the request, and rejects larger bodies with 404.13; the attribute cannot override it. `[DisableRequestSizeLimit]` removes the server cap entirely for the endpoint. Prefer a generous explicit number: no limit means one client can stream until the disk or the connection gives out. ## Raising the form limit ```csharp [HttpPost("api/records")] [RequestSizeLimit(220_000_000)] [RequestFormLimits(MultipartBodyLengthLimit = 209_715_200)] public async Task<IActionResult> Upload(IFormFile scan, CancellationToken ct) { /* ... */ } ``` Other options on `FormOptions` and `[RequestFormLimits]` matter less for files: `MemoryBufferThreshold` (64 KB, the switch from memory to a temp file), `ValueCountLimit` (1024 form entries), `ValueLengthLimit` (4 MB for a text field), and `MultipartHeadersLengthLimit` (16 KB). Global changes go through `builder.Services.Configure<FormOptions>(...)`; a Minimal API endpoint uses `.WithFormOptions(multipartBodyLengthLimit: ...)`. ## What the client sees 1. The server raises a `BadHttpRequestException` with status 413 when the body passes its limit, with the message "Request body too large. The max request body size is 30000000 bytes." 2. Form parsing throws an `InvalidDataException` ("Multipart body length limit 134217728 exceeded.") when a section passes the form limit. 3. In MVC, the form value provider catches both while binding `IFormFile` and records "Failed to read the request form. ..." in `ModelState`; an `[ApiController]` then answers **400** with a validation problem. 4. Where nothing catches the server's exception, the response is the **413** it carries. So a 400 mentioning the request form, on an upload endpoint, is a size limit far more often than a client bug. ## Setting the server limit elsewhere - **For the whole server:** `KestrelServerOptions.Limits.MaxRequestBodySize` (default 30,000,000 bytes) changes every endpoint at once; configuring Kestrel itself is a hosting concern. - **For one request, in code:** `HttpContext.Features.Get<IHttpMaxRequestBodySizeFeature>()` lets middleware set `MaxRequestBodySize` before anything reads the body; once reading has started, `IsReadOnly` is `true` and Kestrel throws an `InvalidOperationException` if you still set it. - **Diagnosing:** when endpoint metadata changes the limit, the routing middleware logs "The maximum request body size has been set to ..." at Debug level, and logs a warning that the limit could not be applied when the feature is already read-only. ## Choosing the numbers - Set the server limit a little above the largest legitimate file to leave room for multipart boundaries and other fields. - Keep the global defaults for every other endpoint; large limits belong only on upload routes. - For files this large, consider streaming with `MultipartReader`, which avoids the 128 MB form limit and the temp-file copy, but keeps the server limit.

  • Two 100 MB files are posted in one form to an action with [RequestSizeLimit(250_000_000)] and default FormOptions. Does it succeed?
    Yes. `MultipartBodyLengthLimit` (128 MB) applies to each multipart section, and each file is 100 MB; the whole body, about 200 MB, is under the 250,000,000-byte server limit set by the attribute. A single 150 MB file in the same request would fail the per-section form limit.
  • Why can [RequestSizeLimit] appear to be ignored even though it is on the action?
    It only works while `IHttpMaxRequestBodySizeFeature` is still writable. If middleware such as request buffering has already started reading the body, the feature is read-only and the attribute cannot change it. On IIS, `maxAllowedContentLength` is enforced by IIS before ASP.NET Core runs, so it must be raised in `web.config` too.

A clinic with a weight limit at the front door and a separate size limit on each box the mailroom accepts: raising the door limit does not make the mailroom take an oversized box, and a box the mailroom would accept never gets in if the door turns it away.

  • Raising FormOptions.MultipartBodyLengthLimit is enough to accept a 150 MB upload.
  • MultipartBodyLengthLimit caps the total size of all files in the request.
  • [RequestSizeLimit] also raises IIS's maxAllowedContentLength.
  • An oversized upload to an [ApiController] action always returns 413.
  • [DisableRequestSizeLimit] is the recommended setting for upload endpoints.