gofiber/fiber · error

cache: failed to store key %q: %w

Error message

cache: failed to store key %q: %w

What it means

Thrown at middleware/cache/manager.go:174 when storage.SetWithContext fails while persisting a freshly cached item. This is the write-side counterpart of error 140: the storage backend rejected the SET (with TTL). The wrapped %w is the raw driver error.

Source

Thrown at middleware/cache/manager.go:174

			return nil, fmt.Errorf("cache: unexpected raw entry type %T for key %q", value, m.logKey(key))
		}
		return raw, nil
	}

	return nil, errCacheMiss
}

// set data to storage or memory
func (m *manager) set(ctx context.Context, key string, it *item, exp time.Duration) error {
	if m.storage != nil {
		raw, err := it.MarshalMsg(nil)
		if err != nil {
			m.release(it)
			return fmt.Errorf("cache: failed to marshal key %q: %w", m.logKey(key), err)
		}
		if err := m.storage.SetWithContext(ctx, key, raw, exp); err != nil {
			m.release(it)
			return fmt.Errorf("cache: failed to store key %q: %w", m.logKey(key), err)
		}
		m.release(it)
		return nil
	}

	m.memory.Set(key, it, exp)
	return nil
}

// set data to storage or memory
func (m *manager) setRaw(ctx context.Context, key string, raw []byte, exp time.Duration) error {
	if m.storage != nil {
		if err := m.storage.SetWithContext(ctx, key, raw, exp); err != nil {
			return fmt.Errorf("cache: failed to store raw key %q: %w", m.logKey(key), err)
		}
		return nil
	}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Examine the wrapped driver error to pinpoint the backend refusal (OOM, disk-full, auth, timeout).
2. Increase storage capacity or tighten cache TTL/size to fit within the backend's memory budget.
3. Set the storage driver's write timeout below the per-request context deadline so SETs complete or fail before the request is torn down.
4. Make the fiber.ErrorHandler tolerate cache-write failures (log + serve the uncached response) so users are unaffected when storage hiccups.
5. Verify storage credentials and connectivity are still valid at runtime, not just at boot.

Example fix

// before
app.Use(cache.New(cache.Config{ Storage: redis.New() }))

// after: tolerate cache write failures by wrapping the error handler
app.New().ErrorHandler = func(c fiber.Ctx, err error) error {
    var ce *cacheErr
    if strings.HasPrefix(err.Error(), "cache: failed to store") {
        log.Printf("cache write failed (serving uncached): %v", err)
        return c.Next() // already have response; just log
    }
    return fiber.DefaultErrorHandler(c, err)
}

// At boot, validate the storage backend accepts writes.
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
if err := store.SetWithContext(ctx, "__probe__", []byte("ok"), time.Second); err != nil {
    log.Fatalf("cache storage write probe failed: %v", err)
}

if err := m.storage.SetWithContext(ctx, key, raw, exp); err != nil {
    log.Printf("cache write failed for %q (serving uncached): %v", key, err)
    return err // ErrorHandler can downgrade to a non-fatal response
}

When it happens

Trigger: Cache miss path computes a response and tries to store it, but the Storage backend is down, out of space, read-only, or the request ctx was cancelled before the SET completed.

Common situations: Redis OOM or maxmemory eviction policy returning an error; SQLite disk full; storage AUTH expired mid-flight; client disconnect causing ctx cancellation during the SET; network blip.

Related errors

• cache: failed to get key %q from storage: %w
• cache: failed to get raw key %q from storage: %w
• cache: failed to store raw key %q: %w
• cache: failed to delete key %q: %w
• cache: failed to reload key %q after eviction failure: %w

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/055abd1eaf03fdb9.json. Report an issue: GitHub.