{"id":"fc8b47dcf49af0dc","repo":"gofiber/fiber","slug":"cache-failed-to-marshal-key-q-w","errorCode":null,"errorMessage":"cache: failed to marshal key %q: %w","messagePattern":"cache: failed to marshal key %q: %w","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"middleware/cache/manager.go","lineNumber":170,"sourceCode":"\n\tif value := m.memory.Get(key); value != nil {\n\t\traw, ok := value.([]byte)\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"cache: unexpected raw entry type %T for key %q\", value, m.logKey(key))\n\t\t}\n\t\treturn raw, nil\n\t}\n\n\treturn nil, errCacheMiss\n}\n\n// set data to storage or memory\nfunc (m *manager) set(ctx context.Context, key string, it *item, exp time.Duration) error {\n\tif m.storage != nil {\n\t\traw, err := it.MarshalMsg(nil)\n\t\tif err != nil {\n\t\t\tm.release(it)\n\t\t\treturn fmt.Errorf(\"cache: failed to marshal key %q: %w\", m.logKey(key), err)\n\t\t}\n\t\tif err := m.storage.SetWithContext(ctx, key, raw, exp); err != nil {\n\t\t\tm.release(it)\n\t\t\treturn fmt.Errorf(\"cache: failed to store key %q: %w\", m.logKey(key), err)\n\t\t}\n\t\tm.release(it)\n\t\treturn nil\n\t}\n\n\tm.memory.Set(key, it, exp)\n\treturn nil\n}\n\n// set data to storage or memory\nfunc (m *manager) setRaw(ctx context.Context, key string, raw []byte, exp time.Duration) error {\n\tif m.storage != nil {\n\t\tif err := m.storage.SetWithContext(ctx, key, raw, exp); err != nil {\n\t\t\treturn fmt.Errorf(\"cache: failed to store raw key %q: %w\", m.logKey(key), err)","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/gofiber/fiber/blob/9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c/middleware/cache/manager.go#L152-L188","documentation":"Thrown at middleware/cache/manager.go:170 when it.MarshalMsg(nil) fails while serializing a cached item to msgp before writing it to storage. The item struct fields carry msgp `limit` tags (header value limit=16384, cache-control limit=2048, etc.); exceeding those caps, or an internal msgp encoding error, produces this. Marshal failures are rare because msgp encoding is deterministic for these types.","triggerScenarios":"An origin response carries a single header value larger than the 16384-byte msgp limit, a Cache-Control directive block larger than 2048 bytes, or an ETag larger than 256 bytes; the marshal step refuses to emit an oversized field.","commonSituations":"Upstream API returning very large Set-Cookie / Authorization / custom header values that get cached; misbehaving origin injecting a giant Cache-Control; values that grew after a backend change.","solutions":["Inspect the wrapped msgp error to see which field limit was exceeded (e.g. 'limit 16384 hit').","Exclude the offending route from caching via Config.Next, or strip the oversized header before it enters the cached response.","If the limit genuinely must be higher, regenerate msgp after editing the limit tag on the offending field in middleware/cache/manager.go and rebuild.","Cap upstream response header sizes at the reverse proxy / origin so pathological values never reach the cache."],"exampleFix":"// before: caching a route that returns multi-KB headers\napp.Use(cache.New())\n\n// after: skip caching for the offending route\napp.Use(cache.New(cache.Config{\n    Next: func(c fiber.Ctx) bool {\n        return c.Path() == \"/api/huge-headers\"\n    },\n}))","handlingStrategy":"validation","validationCode":"// Before caching a route, verify its responses don't exceed msgp field limits.\n// header value limit=16384, cache-control limit=2048, etag limit=256.\nfunc cacheable(resp *fasthttp.Response) bool {\n    resp.Header.VisitAll(func(k, v []byte) {\n        if len(v) > 16384 { /* will overflow; exclude from cache */ }\n    })\n    return true\n}","typeGuard":null,"tryCatchPattern":"raw, err := it.MarshalMsg(nil)\nif err != nil {\n    log.Printf(\"marshal failed for %q (likely oversized header): %v\", key, err)\n    m.release(it)\n    return err // non-fatal upstream; route is excluded from cache via Next()\n}","preventionTips":["Cap upstream response header sizes at the origin / reverse proxy.","Use Config.Next to skip caching for routes known to produce oversized headers.","Regenerate msgp after editing limit tags; keep encoder/decoder in sync.","Log marshal failures distinctly to spot pathological upstreams quickly."],"tags":["cache","serialization","msgpack","fiber"],"analyzedSha":"9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c","analyzedAt":"2026-08-04T21:44:03.395Z","schemaVersion":2}