{"record":{"id":"09e559f09016f0dd","repo":"juicedata/juicefs","slug":"user-group-quota-is-inconsistent-please-repair-it","errorCode":null,"errorMessage":"user/group quota is inconsistent, please repair it with --repair flag","messagePattern":"user/group quota is inconsistent, please repair it with --repair flag","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/quota.go","lineNumber":1065,"sourceCode":"\treturn nil\n}\n\nfunc (m *baseMeta) checkUGUsage(ctx Context, repair bool, quotas map[string]*Quota) error {\n\tuserUsage, groupUsage, err := m.scanGlobalUserGroupUsage(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"scan global user group usage: %w\", err)\n\t}\n\n\t_, userQuotas, groupQuotas, err := m.en.doLoadQuotas(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"load user/group quotas: %w\", err)\n\t}\n\thasErr := m.compareUGUsage(userUsage, userQuotas, UserQuotaType, quotas)\n\thasErr = m.compareUGUsage(groupUsage, groupQuotas, GroupQuotaType, quotas) || hasErr\n\n\tif !repair {\n\t\tif hasErr {\n\t\t\treturn fmt.Errorf(\"user/group quota is inconsistent, please repair it with --repair flag\")\n\t\t}\n\t\treturn nil\n\t}\n\n\tlogger.Infof(\"Begin to repair user/group quota.\")\n\tif err = m.repairUgUsage(ctx, UserQuotaType, userUsage, userQuotas); err != nil {\n\t\treturn err\n\t}\n\tif err = m.repairUgUsage(ctx, GroupQuotaType, groupUsage, groupQuotas); err != nil {\n\t\treturn err\n\t}\n\n\treturn nil\n}\n\nfunc (m *baseMeta) updateQuotaMetrics() {\n\tm.quotaMu.RLock()\n\tdirQuotasSnapshot := make(map[uint64]Quota)","sourceCodeStart":1047,"sourceCodeEnd":1083,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/quota.go#L1047-L1083","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\njuicefs quota check sqlite3://test.db\n// error: user/group quota is inconsistent, please repair it with --repair flag\n// after\njuicefs quota check sqlite3://test.db --repair","handlingStrategy":"validation","validationCode":"// run check first without --repair and inspect reported inconsistencies\n// $ juicefs quota check $META_URL   -> prints each uid/gid drift\n// only proceed when drift is expected:\nif !operatorConfirmedDrift { return errors.New(\"review reported quota inconsistencies before --repair\") }","typeGuard":null,"tryCatchPattern":"err := cmd.Run()\nif err != nil && strings.Contains(err.Error(), \"quota is inconsistent\") {\n\t// deliberate state: schedule an explicit --repair run in a maintenance window\n\treturn scheduleRepair(cmd.Args, \"--repair\")\n}","preventionTips":["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."],"tags":["quota","consistency","metadata","cli"],"backgroundTag":"invalid-state-transition","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}