valyala/fasthttp · error

invalid trailer value %q

Error message

invalid trailer value %q

What it means

Every byte of a chunked trailer value must be a valid header-value byte. fasthttp throws this when a trailer value contains control characters (other than allowed obs-fold/HTAB) or other bytes disallowed by RFC 7230.

Source

Thrown at header.go:2751

	s.b = src

	for s.next() {
		// Trim trailing whitespace before the colon to normalize headers
		// like "Content-Length :" to "Content-Length:".
		s.key = trimTrailingSpace(s.key)

		if len(s.key) == 0 {
			continue
		}
		// Key bytes were already validated by the scanner.
		disable := disableNormalizing || s.keyHasSpace
		// Forbidden by RFC 7230, section 4.1.2
		if isBadTrailer(s.key) {
			return dest, 0, fmt.Errorf("forbidden trailer key %q", s.key)
		}
		for _, ch := range s.value {
			if !validHeaderValueByte(ch) {
				return dest, 0, fmt.Errorf("invalid trailer value %q", s.value)
			}
		}
		normalizeHeaderKeyValidated(s.key, disable)
		dest = appendArgBytes(dest, s.key, s.value, argsHasValue)
	}
	if s.err != nil {
		return dest, 0, s.err
	}
	return dest, s.r, nil
}

func isBadTrailer(key []byte) bool {
	if len(key) == 0 {
		return true
	}

	switch key[0] | 0x20 {
	case 'a':

View on GitHub (pinned to c96f600972)

Solutions

1. Sanitize the sender: ensure trailer values contain only printable ASCII/obs-text with no bare CR/LF
2. Upgrade or patch the client producing the trailers
3. Reject such requests at an edge proxy before they reach fasthttp
4. Investigate repeated occurrences as potential request-smuggling probes

func validTrailerValue(s string) bool {
    for i := 0; i < len(s); i++ {
        b := s[i]
        if b < 0x20 && b != '\t' { return false }
        if b == 0x7f { return false }
    }
    return true
}

if err := h.Read(br); err != nil && strings.Contains(err.Error(), "invalid trailer value") {
    log.Warn("malformed trailer value — possible smuggling attempt", "remote", ctx.RemoteAddr())
    ctx.ResetConnection()
    return
}

When it happens

Trigger: readTrailer encounters a trailer whose value contains bytes failing validHeaderValueByte — e.g. raw \r, \n (unfolding failure), NUL, or other control characters.

Common situations: Malicious clients injecting CRLF into trailer values (request smuggling attempts); buggy custom HTTP clients writing raw binary into trailers; corrupted streams from faulty intermediaries.

Related errors

• fasthttp: contain forbidden trailer
• fasthttp: error when reading response trailer
• forbidden trailer key %q
• fasthttp: error when reading response headers
• fasthttp: cannot find whitespace in the first line of respon

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/7569090ddf1ee368. Report an issue: GitHub.