invalid requestHashHeader %q, key must not end with "-bin"

Error message

invalid requestHashHeader %q, key must not end with "-bin"

What it means

Returned by ringhash.parseConfig (config.go:72-74) when requestHashHeader (already validated as a key) ends with the suffix "-bin". -bin headers carry binary metadata and cannot be used to derive a string request hash, so they are explicitly rejected by A76 even though they pass ValidateKey. The %q is the header.

Source

Thrown at balancer/ringhash/config.go:73

		return nil, fmt.Errorf("min %v is greater than max %v", cfg.MinRingSize, cfg.MaxRingSize)
	}
	if cfg.MinRingSize > envconfig.RingHashCap {
		cfg.MinRingSize = envconfig.RingHashCap
	}
	if cfg.MaxRingSize > envconfig.RingHashCap {
		cfg.MaxRingSize = envconfig.RingHashCap
	}
	if !envconfig.RingHashSetRequestHashKey {
		cfg.RequestHashHeader = ""
	}
	if cfg.RequestHashHeader != "" {
		cfg.RequestHashHeader = strings.ToLower(cfg.RequestHashHeader)
		// See rules in https://github.com/grpc/proposal/blob/master/A76-ring-hash-improvements.md#explicitly-setting-the-request-hash-key
		if err := metadata.ValidateKey(cfg.RequestHashHeader); err != nil {
			return nil, fmt.Errorf("invalid requestHashHeader %q: %v", cfg.RequestHashHeader, err)
		}
		if strings.HasSuffix(cfg.RequestHashHeader, "-bin") {
			return nil, fmt.Errorf("invalid requestHashHeader %q: key must not end with \"-bin\"", cfg.RequestHashHeader)
		}
	}
	return &cfg, nil
}

View on GitHub (pinned to 03255a9237)

Solutions

Use a non-binary (ASCII string) header as the request hash key: remove the "-bin" suffix.
Ensure clients send that key as a normal string header, not appended with -bin.

Example fix

// before
raw := `{"requestHashHeader": "user-id-bin"}` // -bin suffix -> error

// after
raw := `{"requestHashHeader": "user-id"}`

Defensive patterns

Strategy: validation

Validate before calling

func rejectBinHeader(h string) error {
    if strings.HasSuffix(strings.ToLower(h), "-bin") {
        return errors.New("hash header must not end with -bin")
    }
    return nil
}

Type guard

func isNonBinHeader(h string) bool { return !strings.HasSuffix(strings.ToLower(h), "-bin") }

Prevention

Never reuse a binary (-bin) metadata key as the hash source.
Send the hash key as a normal ASCII string header.

When it happens

Trigger: requestHashHeader is set to something ending in "-bin", e.g. "user-id-bin" or "trace-bin".

Common situations: Reusing an existing binary metadata key name as the hash key. Autocomplete/copy from a -bin header list.

Related errors

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