What causes "transport: timeout string is too long: %q" in grpc/grpc-go?

Capture the raw grpc-timeout header value from the failing request to confirm it exceeds 8 digits.

transport: timeout string is too long: %q

Error message

transport: timeout string is too long: %q

What it means

This error occurs in decodeTimeout when the grpc-timeout header value exceeds 9 characters (8 digits + 1 unit character per the gRPC HTTP/2 spec). This is a protocol-level violation — the spec caps the numeric portion at 8 digits.

Source

Thrown at internal/transport/http_util.go:195

	case millisecond:
		return time.Millisecond, true
	case microsecond:
		return time.Microsecond, true
	case nanosecond:
		return time.Nanosecond, true
	default:
	}
	return
}

func decodeTimeout(s string) (time.Duration, error) {
	size := len(s)
	if size < 2 {
		return 0, fmt.Errorf("transport: timeout string is too short: %q", s)
	}
	if size > 9 {
		// Spec allows for 8 digits plus the unit.
		return 0, fmt.Errorf("transport: timeout string is too long: %q", s)
	}
	unit := timeoutUnit(s[size-1])
	d, ok := timeoutUnitToDuration(unit)
	if !ok {
		return 0, fmt.Errorf("transport: timeout unit is not recognized: %q", s)
	}
	t, err := strconv.ParseUint(s[:size-1], 10, 64)
	if err != nil {
		return 0, err
	}
	const maxHours = math.MaxInt64 / uint64(time.Hour)
	if d == time.Hour && t > maxHours {
		// This timeout would overflow math.MaxInt64; clamp it.
		return time.Duration(math.MaxInt64), nil
	}
	return d * time.Duration(t), nil
}

View on GitHub (pinned to 03255a9237)

Solutions

Capture the raw grpc-timeout header value from the failing request to confirm it exceeds 8 digits.
Fix the client library or proxy generating the oversized value.
Ensure your gRPC client library is up to date with proper timeout encoding.

Example fix

// before (broken): more than 8 digits in timeout
grpc-timeout: "999999999S"

// after (valid): use a larger unit or clamp the value
grpc-timeout: "9999H"

Defensive patterns

Strategy: validation

Validate before calling

func validateGrpcTimeout(s string) error {
    if len(s) > 9 {
        return fmt.Errorf("timeout too long: max 8 digits + unit")
    }
    return nil
}

Prevention

Use a compliant gRPC client library with correct timeout encoding.
When setting very long deadlines, use larger units (H) to avoid exceeding 8 digits.
Monitor server logs for protocol violations to catch non-compliant peers.

When it happens

Trigger: A peer sends a grpc-timeout header with more than 8 digits before the unit, e.g., "123456789S". This violates the gRPC over HTTP/2 specification which limits the value to fit in 8 decimal digits.

Common situations: A buggy or non-compliant gRPC client/library generates an oversized timeout encoding, or an intermediary modifies the header. Extremely large deadline values that overflow the normal encoding could trigger this if the encoding logic is broken.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/b5322968218b0bf0. Report an issue: GitHub.