gofiber/fiber · error

failed to lock

Error message

failed to lock: %w

What it means

Returned when cfg.Lock.Lock(key) fails before executing the request handler. The default in-memory locker does not error, so this only fires with a custom Locker implementation (e.g. a distributed Redis/etcd lock) that fails to acquire the lock — connection error, lock contention timeout, or auth failure.

Solutions

1. Verify the locker backend (Redis/etcd) is reachable and authenticated.
2. Tune the locker's acquisition timeout/TTL to outlast the slowest handler.
3. If lock acquisition is best-effort, fall back to per-process memory lock and accept duplicate execution risk.
4. Ensure exactly one Lock instance is shared across instances (not per-process).

When it happens

Trigger: Providing a custom idempotency.Config.Lock (distributed locker) whose Lock(key) returns a non-nil error. Triggers on locker outage, inability to acquire the lock within the locker's timeout, or a misconfigured locker client.

Common situations: Multi-instance deployment using a Redis-based lock where Redis is unreachable, lock TTL too short causing livelock, locker client not initialized, or auth/ACL rejection by the lock backend.

Related errors

• failed to read response
• failed to save response
• cache: failed to delete key
• cache: failed to reload key
• cache: failed to restore heap index for key

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

Appendix: source

Thrown at middleware/idempotency/idempotency.go:126

		if c.Get(cfg.KeyHeader) == "" {
			return c.Next()
		}

		// Validate key
		key := utils.CopyString(c.Get(cfg.KeyHeader))
		if err := cfg.KeyHeaderValidate(key); err != nil {
			return err
		}

		// First-pass: if the idempotency key is in the storage, get and return the response
		if ok, err := maybeWriteCachedResponse(c, key); err != nil {
			return fmt.Errorf("failed to write cached response at fastpath: %w", err)
		} else if ok {
			return nil
		}

		if err := cfg.Lock.Lock(key); err != nil {
			return fmt.Errorf("failed to lock: %w", err)
		}
		defer func() {
			if err := cfg.Lock.Unlock(key); err != nil {
				log.Errorf("[IDEMPOTENCY] failed to unlock key %q: %v", maskKey(key), err)
			}
		}()

		// Lock acquired. If the idempotency key now is in the storage, get and return the response
		if ok, err := maybeWriteCachedResponse(c, key); err != nil {
			return fmt.Errorf("failed to write cached response while locked: %w", err)
		} else if ok {
			return nil
		}

		// Execute the request handler
		if err := c.Next(); err != nil {
			// If the request handler returned an error, return it and skip idempotency
			return err

View on GitHub (pinned to a105acad6c)