gofiber/fiber · error

limiter: failed to persist state

Error message

limiter: failed to persist state: %w

What it means

Returned by the fixed-window limiter on the increment path: after counting a hit and calling manager.set(reqCtx, key, e, expirationDuration), the storage write failed. The wrapped %w is from manager.set (marshal failure or Storage.SetWithContext failure). The mutex is released before returning; the request is aborted with no rate-limit headers set.

Solutions

1. Verify storage connectivity, capacity, and credentials.
2. If you do not need cross-instance limiting, omit Storage to fall back to in-memory (per-process) limiting that never hits this path.
3. Regenerate msgpack (`make generate`) after middleware upgrades.
4. Tune storage client timeouts and pool size to absorb bursts.

Example fix

// before
app.Use(limiter.New(limiter.Config{Storage: redisClient}))
// after — fall back to memory if Redis unavailable
if redisErr == nil {
    app.Use(limiter.New(limiter.Config{Storage: redisClient}))
} else {
    app.Use(limiter.New(limiter.Config{})) // in-memory
}

When it happens

Trigger: limiter_fixed handler increments currHits and calls manager.set, which either fails to marshal the item (msgpack) or fails to write to the configured Storage. Fires when a shared storage (Redis/MySQL/etc.) is unavailable or rejects the write.

Common situations: Distributed limiter with a Storage backend that is down/overloaded, a storage client with too-small connection pool, msgpack schema drift after upgrade, or context cancellation while persisting.

Related errors

• limiter: failed to get key
• limiter: failed to persist state
• limiter: failed to store key
• limiter: failed to unmarshal key
• cache: failed to delete cached response for key

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

Appendix: source

Thrown at middleware/limiter/limiter_fixed.go:85

			// Check if entry is expired
			e.currHits = 0
			e.exp = ts + expiration
		}

		// Increment hits
		e.currHits++

		// Calculate when it resets in seconds
		resetInSec := e.exp - ts
		windowExpiresAt := e.exp

		// Set how many hits we have left
		remaining := maxRequests - e.currHits

		// Update storage
		if setErr := manager.set(reqCtx, key, e, expirationDuration); setErr != nil {
			mux.Unlock()
			return fmt.Errorf("limiter: failed to persist state: %w", setErr)
		}

		// Unlock entry
		mux.Unlock()

		// Check if hits exceed the max
		if remaining < 0 {
			// Return response with Retry-After header
			// https://tools.ietf.org/html/rfc6584
			if !cfg.DisableHeaders {
				c.Set(fiber.HeaderRetryAfter, utils.FormatUint(resetInSec))
			}

			// Call LimitReached handler
			return cfg.LimitReached(c)
		}

		// Continue stack for reaching c.Response().StatusCode()

View on GitHub (pinned to a105acad6c)