{"record":{"id":"ddb1b60bae93e7f4","repo":"juicedata/juicefs","slug":"list-chunk-prefix-s-failed","errorCode":null,"errorMessage":"list chunk prefix %s failed","messagePattern":"list chunk prefix (.+?) failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/gc.go","lineNumber":589,"sourceCode":"\t\t\t}\n\t\t\tmarker = key\n\t\t}\n\t\tif !hasMore {\n\t\t\tbreak\n\t\t}\n\t\ttoken = nextToken\n\t}\n\treturn nil\n}\n\nfunc scanGcChunkObjectsPrefix(ctx context.Context, blob object.ObjectStorage, prefix string, handle func(object.Object) error) error {\n\tobjs, err := object.ListAll(ctx, blob, prefix, \"\", true, false)\n\tif err != nil {\n\t\treturn errors.Errorf(\"list chunk prefix %s: %s\", prefix, err)\n\t}\n\tfor obj := range objs {\n\t\tif obj == nil {\n\t\t\treturn errors.Errorf(\"list chunk prefix %s failed\", prefix)\n\t\t}\n\t\tif err := handle(obj); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc filterGcObject(ctx context.Context, blob object.ObjectStorage, obj object.Object, maxMtime time.Time, scanned *utils.Bar, skipped *utils.DoubleSpinner) (object.Object, bool) {\n\tif obj.IsDir() {\n\t\treturn nil, false\n\t}\n\tif obj.Size() == 0 || obj.Mtime().Unix() == 0 {\n\t\theadObj, err := blob.Head(ctx, obj.Key())\n\t\tif err != nil {\n\t\t\tlogger.Warnf(\"head %s: %s\", obj.Key(), err)\n\t\t\tscanned.Increment()\n\t\t\tskipped.IncrInt64(obj.Size())","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/cmd/gc.go#L571-L607","documentation":"Defensive error from scanGcChunkObjectsPrefix: after a successful ListAll, the results channel yielded a nil object. Since nil entries would crash or corrupt GC accounting, the function treats it as a listing failure and returns this error naming the prefix. Indicates a bug or race in the object-store list implementation rather than a user mistake.","triggerScenarios":"A storage backend's List implementation pushing a nil `object.Object` into the results channel (backend bug or shutdown race), seen while GC scans chunks/<xx>/.","commonSituations":"Third-party S3-compatible backends with buggy list code; object store connection torn down mid-iteration; JuiceFS version with a known object-storage driver bug.","solutions":["Note the backend type in the volume format and check for known driver bugs; upgrade JuiceFS to the latest release.","Retry the GC to rule out a transient shutdown race.","If reproducible with a specific backend, run with `--debug` and file an issue with the backend name.","Test the backend with a direct listing tool to confirm data integrity under chunks/."],"exampleFix":"// upgrade client and retry\njuicefs version\njuicefs gc $META   # after upgrading to latest juicefs","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"// caller-side nil guard mirroring the library check\nif obj == nil {\n    return fmt.Errorf(\"nil object from listing\")\n}","tryCatchPattern":"if strings.Contains(out, \"list chunk prefix\") && strings.Contains(out, \"failed\") {\n    // backend pushed nil object; upgrade juicefs / report backend bug\n}","preventionTips":["Keep JuiceFS and backend drivers current","Test third-party S3-compatible stores before production use","Report reproducible nil-object listings with backend details"],"tags":["go","object-storage","nil-object","gc","driver-bug"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}