juicedata/juicefs · error

load user/group quotas: %w

Error message

load user/group quotas: %w

What it means

This error wraps a failure from `doLoadQuotas`, the engine-level call that loads all persisted user (uid) and group (gid) quota records from the metadata engine. `checkUGUsage` (pkg/meta/quota.go:1056-1058) needs both the scanned global user/group usage and the stored quota records to compare them during `juicefs quota check`; if the underlying engine (Redis/SQL/KV) fails to enumerate quotas, the error is wrapped with this message. It means the quota consistency check could not even read the quota table — it is not a report of inconsistency itself.

Source

Thrown at pkg/meta/quota.go:1058

	}
	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 {
		return err
	}
	if err = m.repairUgUsage(ctx, GroupQuotaType, groupUsage, groupQuotas); err != nil {
		return err
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Check connectivity to the metadata engine (redis/sql/kv URL) and retry the quota check command.
2. Inspect the wrapped cause (%w) in the error output to identify the engine-specific failure (auth, timeout, missing table).
3. For SQL engines, verify the quota tables exist and match the current JuiceFS schema (re-run migrations or restore a consistent backup).
4. Verify credentials/ACLs on the metadata engine allow reading all keys/rows.

Example fix

// before
_, userQuotas, groupQuotas, err := m.en.doLoadQuotas(ctx)
if err != nil {
	return fmt.Errorf("load user/group quotas: %w", err)
}
// after
_, userQuotas, groupQuotas, err := m.en.doLoadQuotas(ctx)
if err != nil {
	return fmt.Errorf("load user/group quotas: %w", err) // inspect wrapped err; e.g. retry with backoff if it is a transient engine error
}

// before running quota check, verify engine reachability
c, err := net.DialTimeout("tcp", "redis-host:6379", 3*time.Second)
if err != nil { return fmt.Errorf("metadata engine unreachable: %w", err) }
c.Close()

err := meta.CheckQuota(ctx, repair)
if err != nil && strings.Contains(err.Error(), "load user/group quotas") {
	// transient engine failure: retry with backoff
	return retryWithBackoff(3, 2*time.Second, func() error { return meta.CheckQuota(ctx, repair) })
}

When it happens

Trigger: Running `juicefs quota check` (handleQuotaCheck -> checkUGUsage) against a metadata engine whose quota records cannot be read: engine connection failure mid-command, SQL schema/table corruption, Redis scan errors, or the engine returning an error from its doLoadQuotas implementation.

Common situations: Metadata engine restarted or network dropped while the check runs; SQL volume where the quota table is missing/damaged (e.g. partial restore from backup); Redis cluster failover during the scan; insufficient permissions on the metadata store.

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

• invalid quota value: %v
• failed to load %s quotas: %w
• remove user group quota
• drop table userGroupQuota
• The entry of the root inode was not found

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