What causes "list chunks from %s: %s" in juicedata/juicefs?

Retry the GC; transient 5xx/throttle errors from the store are the usual cause.

list chunks from %s: %s

Error message

list chunks from %s: %s

What it means

Error produced by the prefix-walking worker in scanGcChunkObjects when a single-prefix scan (`scanGcChunkObjectsPrefix`) of a hashed chunk prefix fails. The blob name and underlying error are embedded, identifying which object-storage prefix enumeration broke. It aborts that worker, propagating up as a failed GC object listing.

Source

Thrown at cmd/gc.go:515

			select {
			case prefixes <- prefix:
				return nil
			case <-scanCtx.Done():
				return scanCtx.Err()
			}
		})
	})

	for range threads {
		eg.Go(func() error {
			for {
				select {
				case prefix, ok := <-prefixes:
					if !ok {
						return nil
					}
					if err := scanGcChunkObjectsPrefix(scanCtx, blob, prefix, handle); err != nil {
						return errors.Errorf("list chunks from %s: %s", blob, err)
					}
					prefixSpin.Increment()
				case <-scanCtx.Done():
					return scanCtx.Err()
				}
			}
		})
	}
	return eg.Wait()
}

func walkGcChunkObjectPrefixes(ctx context.Context, blob object.ObjectStorage, prefix string, depth int, allowFallback bool, fn func(string) error) error {
	seenPrefixes := make(map[string]struct{})
	var marker, token string
	firstPage := true
	for {
		objs, hasMore, nextToken, err := blob.List(ctx, prefix, marker, token, "/", gcObjectListBatch, true)
		if err != nil {

View on GitHub (pinned to c9a67b23e8)

Solutions

Retry the GC; transient 5xx/throttle errors from the store are the usual cause.
Lower `--threads` to reduce parallel ListObjects pressure on the object store.
Check store-side rate limits (S3 request rate per prefix) and credentials validity.
Inspect the embedded error for 503/timeout and re-run during lower load.
If the volume is huge, use `--ext-sort` mode which handles large listings with external sort.

Example fix

// before
juicefs gc --threads 256 redis://localhost/1
// after
juicefs gc --threads 16 redis://localhost/1

Defensive patterns

Strategy: retry

Validate before calling

# probe one prefix before GC
aws s3api list-objects-v2 --bucket $BUCKET --prefix chunks/ --max-items 1 > /dev/null

Try / catch

if strings.Contains(out, "list chunks from ") {
    // likely transient store error; exponential backoff and re-run gc
}

Prevention

Size --threads under the store's per-prefix request-rate limits
Retry GC on 5xx/throttle errors
Keep object store endpoints on a stable network path

When it happens

Trigger: During `juicefs gc`, listing a specific 2-hex-character prefix under chunks/ fails due to object-store ListObjects errors: throttling (503 SlowDown), expired credentials, transient network errors, or ctx cancellation racing with the list call.

Common situations: Very large buckets where each prefix listing is slow and the object store rate-limits parallel prefix listings; temporary S3 unavailability; minio restart mid-GC; context cancelled because another worker failed first.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/47e6e7e2c70b4f44. Report an issue: GitHub.