gofiber/fiber · error

cache: failed to store raw key

Error message

cache: failed to store raw key %q: %w

What it means

Returned by manager.setRaw when the external Storage's SetWithContext fails while persisting the separated raw response body (key+"_body"). Because setRaw runs before the metadata set in the two-write external-storage flow, this failure means no metadata key was written and cleanup is straightforward.

Solutions

1. Check the wrapped error for size-limit vs connectivity causes.
2. Verify the response body size fits within the backend's max value/bulk size (e.g. Redis proto-max-bulk-len, MongoDB document 16MB cap).
3. Configure the cache to skip oversized bodies or cap MaxBytes appropriately.
4. Treat as cache miss on the next request — ensure the request itself does not fail.

Example fix

// before: raw-body store failure aborts the cached response
if err := manager.setRaw(reqCtx, key+"_body", e.body, exp); err != nil {
    return err
}

// after: downgrade to a warning and skip caching this response
if err := manager.setRaw(reqCtx, key+"_body", e.body, exp); err != nil {
    log.Warn("cache raw-body store skipped:", err)
    return nil // do not cache; handler response still served
}

// Confirm a representative body size fits the backend's value-size cap before enabling caching.
func bodyFitsBackend(body []byte, maxSize int) error {
    if len(body) > maxSize {
        return fmt.Errorf("body %d bytes exceeds backend max %d", len(body), maxSize)
    }
    return nil
}

if err := manager.setRaw(reqCtx, key+"_body", e.body, exp); err != nil {
    if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
        return
    }
    log.Warn("raw-body store skipped:", err)
    // do not fail the request; skip caching this response
}

When it happens

Trigger: External-Storage cache store where the raw body write (manager.setRaw, called at cache.go:973) fails: backend down, write timeout, payload too large for the backend's value-size limit (Redis max bulk-payload), quota exceeded, context cancellation.

Common situations: Caching large response bodies that exceed the storage backend's per-value size cap; Redis/MongoDB under memory pressure; network instability; client disconnect during streaming response.

Related errors

• cache: failed to get raw key
• cache: failed to store key
• cache: failed to delete key
• cache: failed to get key
• csrf: failed to store key

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

Appendix: source

Thrown at middleware/cache/manager.go:188

			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
	}

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

// delete data from storage or memory
func (m *manager) del(ctx context.Context, key string) error {
	if m.storage != nil {
		if err := m.storage.DeleteWithContext(ctx, key); err != nil {
			return fmt.Errorf("cache: failed to delete key %q: %w", m.logKey(key), err)
		}
		return nil
	}

	m.memory.Delete(key)

View on GitHub (pinned to a105acad6c)