What causes "failed to convert %q to uint" in grpc/grpc-go?

Replace the oversized value with a realistic byte limit (e.g. `256`, `1024`).

failed to convert %q to uint

Error message

failed to convert %q to uint

What it means

Raised by parseHeaderMessageLengthConfig in the header-only branch `{h:N}`. The regex already matched `N` as digits (`\d+`), so strconv.ParseUint only fails when N exceeds the uint64 maximum (18446744073709551615) or is otherwise unparseable at this stage. Wrapped as 'failed to convert %q to uint'.

Source

Thrown at internal/binarylog/env_config.go:169

	service = match[1]
	method = match[2]
	suffix = match[3]
	return
}

// Turn "{h:123;m:345}" into 123, 345.
//
// Return maxUInt if length is unspecified.
func parseHeaderMessageLengthConfig(c string) (hdrLenStr, msgLenStr uint64, err error) {
	if c == "" {
		return maxUInt, maxUInt, nil
	}
	// Header config only.
	if match := headerConfigRegexp.FindStringSubmatch(c); match != nil {
		if s := match[1]; s != "" {
			hdrLenStr, err = strconv.ParseUint(s, 10, 64)
			if err != nil {
				return 0, 0, fmt.Errorf("failed to convert %q to uint", s)
			}
			return hdrLenStr, 0, nil
		}
		return maxUInt, 0, nil
	}

	// Message config only.
	if match := messageConfigRegexp.FindStringSubmatch(c); match != nil {
		if s := match[1]; s != "" {
			msgLenStr, err = strconv.ParseUint(s, 10, 64)
			if err != nil {
				return 0, 0, fmt.Errorf("failed to convert %q to uint", s)
			}
			return 0, msgLenStr, nil
		}
		return 0, maxUInt, nil
	}

View on GitHub (pinned to 0c51461d27)

Solutions

Replace the oversized value with a realistic byte limit (e.g. `256`, `1024`).
To mean 'no limit on headers', omit the number entirely: `Foo/Bar{h}`.
Validate that the number is within [0, 18446744073709551615] before constructing the string.

Example fix

// before
config := "Foo/Bar{h:99999999999999999999999}"
// after
config := "Foo/Bar{h}"

Defensive patterns

Strategy: validation

Validate before calling

const maxU64 = uint64(18446744073709551615) // math.MaxUint64
func validLengthField(s string) bool {
    if s == "" { return true } // omit => unlimited
    n, err := strconv.ParseUint(s, 10, 64)
    return err == nil && n <= maxU64
}

Try / catch

Parse each {h:N} field yourself with strconv.ParseUint(_,10,64) before assembling the filter; on error replace with an empty value or a sane cap.

Prevention

Use an empty header number to mean 'unlimited' instead of a huge number.
Bound user-supplied byte limits to a realistic maximum (e.g. 1<<20).
Unit-test the filter builder with edge-case magnitudes.

When it happens

Trigger: A config like `Foo/Bar{h:99999999999999999999999}` where the header byte limit overflows uint64. Effectively any header length that does not fit in 64 bits.

Common situations: Pasting a very large number intending 'unlimited'; misreading the doc and supplying a value with too many digits; generated configs that concatenate magnitudes.

Related errors

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/02bf6093edc1e956. Report an issue: GitHub.