juicedata/juicefs · error

scan global user group usage: %v

Error message

scan global user group usage: %v

What it means

ScanUserGroupUsage first aggregates global per-user and per-group usage via scanGlobalUserGroupUsage; if that scan fails, the error is wrapped with this prefix. This runs during quota operations that need user/group usage data (e.g. quota set with strict checks, loadDumpedQuotas).

Source

Thrown at pkg/meta/quota.go:706

		return wrapErr(st)
	}

	_, err := m.en.doSetQuota(ctx, DirQuotaType, uint64(ino), &Quota{
		UsedSpace:  int64(sum.Size) - align4K(0),
		UsedInodes: int64(sum.Dirs+sum.Files) - 1,
		MaxSpace:   -1,
		MaxInodes:  -1,
	})
	if err != nil {
		return wrapErr(err)
	}
	return nil
}

func (m *baseMeta) ScanUserGroupUsage(ctx Context) error {
	userUsage, groupUsage, err := m.scanGlobalUserGroupUsage(ctx)
	if err != nil {
		return fmt.Errorf("scan global user group usage: %v", err)
	}

	var userQuotasSnapshot map[uint64]*Quota
	var groupQuotasSnapshot map[uint64]*Quota

	m.quotaMu.Lock()
	// Reset user and group quotas
	m.userQuotas = make(map[uint64]*Quota)
	m.groupQuotas = make(map[uint64]*Quota)
	for uid, usage := range userUsage {
		m.userQuotas[uid] = &Quota{
			MaxSpace:   -1,
			MaxInodes:  -1,
			UsedSpace:  int64(usage.Size),
			UsedInodes: int64(usage.Files),
		}
	}
	for gid, usage := range groupUsage {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Retry the operation; transient backend errors often resolve on a second attempt.
2. Check connectivity and health of the metadata engine (redis-cli ping / database logs).
3. Inspect the wrapped inner error (%v suffix) for the root cause and address it specifically.
4. Increase client timeouts or reduce concurrent load if the scan times out on large volumes.

redis-cli -u "$META_URL" ping  # verify metadata engine reachable first

for i in 1 2 3; do
  if err=$(juicefs quota set ... 2>&1); then break; fi
  sleep $((i*5))
done

When it happens

Trigger: The underlying engine scan over usage keys fails — e.g. Redis/SQL/KV backend errors, timeouts, or connection loss while iterating global user/group usage entries.

Common situations: Redis or SQL metadata engine temporarily unreachable or slow during a quota operation on a large volume; network blip between client and metadata backend; backend returning partial/corrupt quota usage records.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• scan global user group usage: %w
• failed to load %q quotas: %w
• no quota for any trash directory
• Aborted.
• cannot disable dir stats when there are still %d dir quotas:

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