juicedata/juicefs · error

scan slice

Error message

scan slice

What it means

In scanPendingSlices, after slice refs are listed, the user-supplied scan callback is invoked per sliceRef (id, size) to decide whether the slice can be deleted. Any error returned by that callback is wrapped as "scan slice" and aborts the pending-slice scan.

Source

Thrown at pkg/meta/sql.go:4139

	if scan == nil {
		return nil
	}
	var refs []sliceRef
	err := m.simpleTxn(ctx, func(tx *xorm.Session) error {
		if ok, err := tx.IsTableExist(&sliceRef{}); err != nil {
			return err
		} else if !ok {
			return nil
		}
		return tx.Where("refs <= 0").Find(&refs)
	})
	if err != nil {
		return errors.Wrap(err, "scan slice refs")
	}
	for _, ref := range refs {
		clean, err := scan(ref.Id, ref.Size)
		if err != nil {
			return errors.Wrap(err, "scan slice")
		}
		if clean {
			// TODO: m.deleteSlice(ref.Id, ref.Size)
			// avoid lint warning
			_ = clean
		}
	}
	return nil
}

func (m *dbMeta) scanPendingFiles(ctx Context, scan pendingFileScan) error {
	if scan == nil {
		return nil
	}

	var dfs []delfile
	if err := m.simpleTxn(ctx, func(s *xorm.Session) error {
		if ok, err := s.IsTableExist(&delfile{}); err != nil {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Check object storage connectivity and credentials, then re-run `juicefs gc`
2. Inspect the wrapped cause to find the failing slice and object store error
3. Re-run gc after object store issues resolve; the scan restarts from the ref list
4. Verify no manual deletion of chunks happened out-of-band (use `juicefs gc` instead of deleting objects directly)

// verify object storage is reachable before gc
_, err := osClient.BucketExists(bucket)

if err != nil && strings.Contains(err.Error(), "scan slice") {
    // cause is from the scan callback (usually object storage); fix and re-run gc
}

When it happens

Trigger: `juicefs gc --delete-slices` on SQL metadata where the per-slice scan callback (checking object storage / slice state) returns an error for a given slice id.

Common situations: Object storage unreachable or returning errors during gc; a sliceRef row pointing to inconsistent state; rate limiting or timeouts on the object store during large gc runs.

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

• not inserted or updated
• list all blocks: %s
• list chunks from %s: %s
• delimiter list returned nested object %s
• list chunk prefix %s: %s

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