Request Body Limits in Go: Why io.LimitReader Masks ErrorsArticle · digest for October 28
European BD comic illustration of a Go backend developer spotting a hidden HTTP request body limit bug.
Article3 sections≈ 5 min

Request Body Limits in Go: Why io.LimitReader Masks Errors

Any backend engineer exposing public HTTP endpoints has to guard against Denial of Service attacks. If your handler blindly calls io.ReadAll(r.Body) or hands the stream straight to json.NewDecoder(r.Body), an attacker only needs to send a 5 GB HTTP POST request to exhaust your RAM and crash the server with an Out of Memory (OOM) kill.

The fix seems obvious: cap how many bytes the server will read from the request body. Yet right at that step, thousands of Go developers reach for the wrong standard-library tool: io.LimitReader.

At first glance, io.LimitReader looks made for the job. In production, though, that innocent wrapper turns into a ticking time bomb.

Anatomy of the Bug: Why io.LimitReader Hides Oversized Payloads

Let's look at how io.LimitReader actually works in Go's standard library. It wraps an underlying io.Reader and reads at most N bytes from it. The moment that limit is reached, every subsequent Read() call returns 0, io.EOF.

See the catch?

To json.NewDecoder or io.ReadAll, getting io.EOF means the data stream ended cleanly and normally! Imagine a client sends a 2 MB JSON payload against a 1 MB limit:

  1. io.LimitReader dutifully reads the first megabyte and stops.
  2. The JSON decoder tries to read the rest of the object, hits io.EOF mid-structure, and returns a generic syntax error: unexpected EOF or syntax error.
  3. Your handler catches that error and replies with HTTP 400 Bad Request.

That creates a double failure in your API logic:

  • Your server never realizes it was hit with an oversized payload or attack, and logs misleading syntax errors.
  • A legitimate client gets a confusing "Invalid JSON syntax" message instead of an honest HTTP 413 Payload Too Large.
  • Worse still, if the body happens to get truncated right at the boundary of a valid nested object, the parser could accept a mangled payload and write corrupted data to your database.

The Right Tool: net/http.MaxBytesReader

To handle this properly, Go's standard library provides http.MaxBytesReader.

Unlike the general-purpose io.LimitReader, http.MaxBytesReader is built specifically to cooperate with http.ResponseWriter:

  1. If the body exceeds the limit by even a single byte, Read() returns a typed *http.MaxBytesError.
  2. It automatically sets an internal flag on the server's network connection, preventing the handler from reading any further from the socket.
  3. The server cleanly closes the connection or sends Connection: close, stopping the client from endlessly dumping unwanted bytes down the pipe.

Here is a clean reference handler for safely decoding JSON:

package main

import (
    "encoding/json"
    "errors"
    "fmt"
    "net/http"
)

type UserPayload struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func handleUserRegistration(w http.ResponseWriter, r *http.Request) {
    // Hard body size limit: no more than 1 MB
    const maxUploadSize = 1024 * 1024
    r.Body = http.MaxBytesReader(w, r.Body, maxUploadSize)

    var payload UserPayload
    decoder := json.NewDecoder(r.Body)
    decoder.DisallowUnknownFields()

    if err := decoder.Decode(&payload); err != nil {
        var maxBytesErr *http.MaxBytesError
        if errors.As(err, &maxBytesErr) {
            // Honest notification when the request exceeds the allowed size
            http.Error(w, fmt.Sprintf("Request body exceeds the %d-byte limit", maxBytesErr.Limit), http.StatusRequestEntityTooLarge)
            return
        }

        http.Error(w, fmt.Sprintf("Invalid JSON syntax: %v", err), http.StatusBadRequest)
        return
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"status":"success"}`))
}

Notice the errors.As(err, &maxBytesErr) check: it cleanly separates quota violations from malformed JSON.

Wrapping It in a Reusable HTTP Middleware

If your service has dozens of endpoints, repeating that limit in every handler is tedious and easy to forget. Moving it into global HTTP middleware is much safer:

package main

import (
    "net/http"
)

// LimitBodySizeMiddleware caps incoming request body sizes across all routes
func LimitBodySizeMiddleware(maxBytes int64) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Enforce the read limit only on methods that carry a body
            if r.Method == http.MethodPost || r.Method == http.MethodPut || r.Method == http.MethodPatch {
                r.Body = http.MaxBytesReader(w, r.Body, maxBytes)
            }
            next.ServeHTTP(w, r)
        })
    }
}

We looked at another low-level Go memory pitfall earlier in major page faults in Go and why mmap can slow your program down, and keeping tight control over network buffers is another essential piece of backend reliability.

Use the platform's purpose-built tools: swapping one line of code eliminates phantom parsing errors and keeps your API predictable for callers.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 2