What causes "scan slice refs" in juicedata/juicefs?

Re-run `juicefs gc` after confirming DB connectivity

scan slice refs

Error message

scan slice refs

What it means

scanPendingSlices lists sliceRef rows whose reference count has dropped to <= 0 so stale slices can be removed. If the SELECT of these slice refs fails, the error is wrapped as "scan slice refs" and `juicefs gc` fails.

Source

Thrown at pkg/meta/sql.go:4134

	}
	return nil
}

func (m *dbMeta) scanPendingSlices(ctx Context, scan pendingSliceScan) error {
	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

View on GitHub (pinned to c9a67b23e8)

Solutions

Re-run `juicefs gc` after confirming DB connectivity
Fix the underlying DB error shown in the wrapped cause (privileges, locks, connectivity)
Run gc with a stable direct DB connection rather than through flaky proxies
Check table integrity if corruption is suspected

Defensive patterns

Strategy: retry

Validate before calling

// verify read access to slice_ref before gc
rows, err := db.Query("SELECT 1 FROM slice_ref LIMIT 1")

Try / catch

if err != nil && strings.Contains(err.Error(), "scan slice refs") {
    // fix underlying SQL error (cause is wrapped) then re-run gc
}

Prevention

Grant SELECT on slice_ref to the metadata user
Avoid network paths that drop long-lived DB connections
Run `CHECK TABLE`/integrity checks if failures persist

When it happens

Trigger: `juicefs gc` (pending-slice scan) on a SQL volume: `SELECT ... FROM slice_ref WHERE refs <= 0` fails due to connection failure, lock timeout, or missing/corrupt slice_ref table (IsTableExist error propagates here too).

Common situations: DB connectivity issues during gc; MySQL wait_timeout killing idle connections mid-scan; table-level corruption; insufficient SELECT privileges added mid-run.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

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