What causes "scan global user group usage: %w" in juicedata/juicefs?

Inspect the wrapped (%w) underlying error to find the actual scan/backend failure and fix it.

scan global user group usage: %w

Error message

scan global user group usage: %w

What it means

Raised by baseMeta.checkUGUsage (pkg/meta/quota.go:1053) when scanGlobalUserGroupUsage fails while walking the whole tree to compute per-uid/per-gid usage. This scan is the input to all user/group quota checks, so the check cannot proceed. The real cause is wrapped via %w.

Source

Thrown at pkg/meta/quota.go:1053

func (m *baseMeta) repairUgUsage(ctx Context, qtype uint32, usageMap map[uint64]*Summary, quotaMap map[uint64]*Quota) error {
	idType := "uid"
	if qtype == GroupQuotaType {
		idType = "gid"
	}
	if err := m.en.cleanUgUsage(ctx, qtype); err != nil {
		return fmt.Errorf("clean %s quotas: %w", idType, err)
	}
	if err := m.repairUsage(ctx, usageMap, quotaMap, qtype); err != nil {
		return fmt.Errorf("set %s quota: %w", idType, err)
	}
	return nil
}

func (m *baseMeta) checkUGUsage(ctx Context, repair bool, quotas map[string]*Quota) error {
	userUsage, groupUsage, err := m.scanGlobalUserGroupUsage(ctx)
	if err != nil {
		return fmt.Errorf("scan global user group usage: %w", err)
	}

	_, userQuotas, groupQuotas, err := m.en.doLoadQuotas(ctx)
	if err != nil {
		return fmt.Errorf("load user/group quotas: %w", err)
	}
	hasErr := m.compareUGUsage(userUsage, userQuotas, UserQuotaType, quotas)
	hasErr = m.compareUGUsage(groupUsage, groupQuotas, GroupQuotaType, quotas) || hasErr

	if !repair {
		if hasErr {
			return fmt.Errorf("user/group quota is inconsistent, please repair it with --repair flag")
		}
		return nil
	}

	logger.Infof("Begin to repair user/group quota.")
	if err = m.repairUgUsage(ctx, UserQuotaType, userUsage, userQuotas); err != nil {

View on GitHub (pinned to c9a67b23e8)

Solutions

Inspect the wrapped (%w) underlying error to find the actual scan/backend failure and fix it.
Retry when the metadata engine is healthy and metadata writes are quiescent.
For very large filesystems, run during low load / increase client timeouts so the scan can complete.
Verify engine health (`juicefs status`) before re-running the quota check.

Example fix

// before: scan fails under load
$ juicefs quota check --uid 1000 /mnt/jfs
// after: run when cluster quiet / backend healthy
$ juicefs status sqlite3://test.db  # confirm healthy
$ juicefs quota check --uid 1000 /mnt/jfs

Defensive patterns

Strategy: retry

Validate before calling

// precheck engine health and skip check if the scan source is unavailable
if _, err := m.en.doLoadQuotas(ctx); err != nil {
    return fmt.Errorf("skip U/G quota check; engine unhealthy: %w", err)
}

Try / catch

err := checkUGUsage(ctx, repair, quotas)
if err != nil && strings.Contains(err.Error(), "scan global user group usage") {
    time.Sleep(30 * time.Second)
    err = checkUGUsage(ctx, repair, quotas) // transient scan failures often clear
}

Prevention

Run user/group quota checks during low-traffic windows on large filesystems.
Increase client timeouts for huge trees so the global scan completes.
Check `juicefs status` / engine logs before initiating global scans.
Avoid concurrent heavy metadata mutations during the scan.

When it happens

Trigger: `juicefs quota check` with user/group quota type (handleQuotaCheck routes U/G quotas to checkUGUsage), when the global traversal (GetSummary-like walk over all inodes / usage scans) returns an error — metadata engine read failure, truncated scan, or internal walk error.

Common situations: Large filesystems hitting scan timeouts; metadata backend connectivity issues; concurrent metadata mutations confusing the scan; corrupted or inaccessible inode ranges.

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

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