user/group quota is inconsistent, please repair it with --re

Error message

user/group quota is inconsistent, please repair it with --repair flag

What it means

This is an intentional, expected result of `juicefs quota check`: after comparing the scanned global user/group usage against the stored user/group quota records (compareUGUsage at pkg/meta/quota.go:1060-1061), at least one quota's used-space/used-inode accounting disagrees with reality. The command refuses to proceed without `--repair`, because repairing rewrites usage counters and should be an explicit decision.

Source

Thrown at pkg/meta/quota.go:1065

	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
	}

	return nil
}

func (m *baseMeta) updateQuotaMetrics() {
	m.quotaMu.RLock()
	dirQuotasSnapshot := make(map[uint64]Quota)

View on GitHub (pinned to c9a67b23e8)

Solutions

Re-run with the repair flag: `juicefs quota check <META-URL> --repair` (or the documented repair path) to rebuild user/group usage from the scan.
Before repairing, review the inconsistencies the check prints (which uids/gids and how far off) to confirm they are expected.
Run the check/repair during low activity so usage does not change between scan and repair.
Upgrade clients to a consistent version first if mixed versions caused counter drift.

Example fix

// before
juicefs quota check sqlite3://test.db
// error: user/group quota is inconsistent, please repair it with --repair flag
// after
juicefs quota check sqlite3://test.db --repair

Defensive patterns

Strategy: validation

Validate before calling

// run check first without --repair and inspect reported inconsistencies
// $ juicefs quota check $META_URL   -> prints each uid/gid drift
// only proceed when drift is expected:
if !operatorConfirmedDrift { return errors.New("review reported quota inconsistencies before --repair") }

Try / catch

err := cmd.Run()
if err != nil && strings.Contains(err.Error(), "quota is inconsistent") {
	// deliberate state: schedule an explicit --repair run in a maintenance window
	return scheduleRepair(cmd.Args, "--repair")
}

Prevention

Schedule periodic `quota check` runs to catch drift early.
Avoid restoring metadata backups without re-running usage scans/repair afterwards.
Keep all clients on a consistent JuiceFS version to prevent counter drift.
Take a metadata backup before running --repair.

When it happens

Trigger: Running `juicefs quota check` (without `--repair`) on a volume where cached/persisted UsedSpace or UsedInodes for any uid or gid differs from the actual values computed by scanning the filesystem — e.g. after crashes, direct metadata edits, restores, or earlier bugs that drifted the counters.

Common situations: After restoring metadata from a backup that is older than the data; after an unclean shutdown lost quota usage updates; after deleting files with a mismatched engine version; monitoring/alerting noticing wrong quota usage metrics.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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