{"record":{"id":"3f37cb45810cd9de","repo":"containerd/containerd","slug":"referrers-index-size-d-exceeds-maximum-allowed-d","errorCode":null,"errorMessage":"referrers index size %d exceeds maximum allowed %d: %w","messagePattern":"referrers index size (.+?) exceeds maximum allowed (.+?): %w","errorType":"error_code","errorClass":"errdefs.ErrNotFound","httpStatus":404,"severity":"warning","filePath":"core/remotes/docker/referrers.go","lineNumber":51,"sourceCode":")\n\nfunc (r dockerFetcher) FetchReferrers(ctx context.Context, dgst digest.Digest, opts ...remotes.FetchReferrersOpt) ([]ocispec.Descriptor, error) {\n\tvar config remotes.FetchReferrersConfig\n\tfor _, opt := range opts {\n\t\topt(ctx, &config)\n\t}\n\trc, size, err := r.openReferrers(ctx, dgst, config)\n\tif err != nil {\n\t\tif errdefs.IsNotFound(err) {\n\t\t\treturn []ocispec.Descriptor{}, nil\n\t\t}\n\t\treturn nil, err\n\t}\n\tdefer rc.Close()\n\tif size < 0 {\n\t\tsize = MaxManifestSize\n\t} else if size > MaxManifestSize {\n\t\treturn nil, fmt.Errorf(\"referrers index size %d exceeds maximum allowed %d: %w\", size, MaxManifestSize, errdefs.ErrNotFound)\n\t}\n\n\tvar index ocispec.Index\n\tdec := json.NewDecoder(io.LimitReader(rc, size))\n\tif err := dec.Decode(&index); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to decode referrers index: %w\", err)\n\t}\n\tif _, err := dec.Token(); !errors.Is(err, io.EOF) {\n\t\treturn nil, fmt.Errorf(\"unexpected data after JSON object\")\n\t}\n\n\tif len(config.ArtifactTypes) == 0 {\n\t\treturn index.Manifests, nil\n\t}\n\n\tvar referrers []ocispec.Descriptor\n\ttFilter := map[string]struct{}{}\n\tfor _, t := range config.ArtifactTypes {","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/containerd/containerd/blob/4246446a2bf7d03837b0244118d858799393bd80/core/remotes/docker/referrers.go#L33-L69","documentation":"FetchReferrers enforces MaxManifestSize on the referrers index before decoding; if the reported content length exceeds the limit, it fails, wrapping errdefs.ErrNotFound. This bounds memory usage and treats oversized/abnormal referrers indexes as effectively absent. The '%w' verb with ErrNotFound means callers may treat it as 'no referrers found'.","triggerScenarios":"Calling FetchReferrers (or FetchReferrers with filters) against a repository whose referrers index blob Content-Length exceeds MaxManifestSize (typically 4 MiB).","commonSituations":"A repository with an enormous number of referrer manifests (accumulated signatures/SBOMs) producing a giant tag_schema2/referrers index; a misbehaving registry reporting a bogus large size.","solutions":["Prune/referrer-GC the repository to reduce the referrers index size","Use paged referrers APIs where available instead of fetching the whole index","Increase MaxManifestSize if your deployment truly needs bigger indexes (recompile/config) and accept the memory cost","Treat the wrapped ErrNotFound as 'referrers unavailable' and fall back to scanning manifests"],"exampleFix":"// before\nreferrers, err := fetcher.FetchReferrers(ctx, desc)\n// after: tolerate oversized index\nreferrers, err := fetcher.FetchReferrers(ctx, desc)\nif err != nil && errors.Is(err, errdefs.ErrNotFound) {\n    referrers = nil // fall back\n}","handlingStrategy":"fallback","validationCode":"// check referrers index size head-of-time if you control the endpoint\nresp, _ := http.Head(referrersURL)\nif n := resp.ContentLength; n > 4<<20 { /* avoid full fetch; use paging */ }","typeGuard":null,"tryCatchPattern":"referrers, err := fetcher.FetchReferrers(ctx, desc)\nif err != nil && errors.Is(err, errdefs.ErrNotFound) {\n    referrers = nil // degrade gracefully: treat as no referrers\n}","preventionTips":["Run referrer garbage collection on busy repositories","Keep per-subject referrer counts bounded","Prefer registries supporting the paged referrers API"],"tags":["size-limit","referrers","oci"],"backgroundTag":"manifest-size-limit-exceeded","analyzedSha":"4246446a2bf7d03837b0244118d858799393bd80","analyzedAt":"2026-09-02T00:14:43.053Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}