gofiber/fiber · warning · ErrInvalidIdempotencyKey

%w: invalid length: %d != %d

Error message

%w: invalid length: %d != %d

What it means

Returned by the default KeyHeaderValidate in idempotency.ConfigDefault when the X-Idempotency-Key header is not exactly 36 characters (UUID length). It wraps ErrInvalidIdempotencyKey with the observed and expected lengths so callers can distinguish length errors from other key problems. The request is rejected before any storage or lock work.

Source

Thrown at middleware/idempotency/config.go:69

	// DisableValueRedaction turns off masking idempotency keys in logs and errors when set to true.
	//
	// Optional. Default: false
	DisableValueRedaction bool
}

// ConfigDefault is the default config
var ConfigDefault = Config{
	Next: func(c fiber.Ctx) bool {
		// Skip middleware if the request was done using a safe HTTP method
		return fiber.IsMethodSafe(c.Method())
	},

	Lifetime: 30 * time.Minute,

	KeyHeader: "X-Idempotency-Key",
	KeyHeaderValidate: func(k string) error {
		if l, wl := len(k), 36; l != wl { // UUID length is 36 chars
			return fmt.Errorf("%w: invalid length: %d != %d", ErrInvalidIdempotencyKey, l, wl)
		}

		return nil
	},

	KeepResponseHeaders: nil,

	Lock: nil, // Set in configDefault so we don't allocate data here.

	Storage:               nil, // Set in configDefault so we don't allocate data here.
	DisableValueRedaction: false,
}

// Helper function to set default values
func configDefault(config ...Config) Config {
	// Return default config if nothing provided
	if len(config) < 1 {
		cfg := ConfigDefault

View on GitHub (pinned to a105acad6c)

Solutions

1. Send a canonical 36-char UUID (uuid.NewString()) in X-Idempotency-Key.
2. If you use a different key format, override Config.KeyHeaderValidate with a validator that accepts it.
3. Strip whitespace from the header before validation if clients/proxies add it.
4. Return a 400 to clients with a clear message so they correct the key format.

Example fix

// before
KeyHeaderValidate: nil // uses default 36-char UUID check
// after — accept any non-empty opaque key
KeyHeaderValidate: func(k string) error {
    if k == "" { return errors.New("empty idempotency key") }
    return nil
}

if len(c.Get("X-Idempotency-Key")) != 36 {
    return c.Status(fiber.StatusBadRequest).SendString("idempotency key must be a 36-char UUID")
}

func isUUIDLength(k string) bool { return len(k) == 36 }

When it happens

Trigger: A client sends a non-safe HTTP method (POST/PUT/PATCH/DELETE) with an X-Idempotency-Key header whose length is not 36 characters — e.g. a truncated UUID, a UUID with braces, a non-UUID opaque token, or accidental whitespace.

Common situations: Clients sending a ULID/UUID-without-dashes/nanoID instead of a canonical UUID, frontends trimming/normalizing the header, proxies appending characters, or a custom KeyHeaderValidate that the developer forgot to override when moving to a non-UUID key format.

Related errors

• failed to bind to response headers: %w
• minLen constraint requires an argument
• maxLen constraint requires an argument
• len constraint requires an argument
• betweenLen constraint requires two arguments

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/c1c901e57040134e. Report an issue: GitHub.