{"record":{"id":"5043a2a90d6880a8","repo":"juicedata/juicefs","slug":"scan-global-user-group-usage-w","errorCode":null,"errorMessage":"scan global user group usage: %w","messagePattern":"scan global user group usage: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/quota.go","lineNumber":1053,"sourceCode":"\nfunc (m *baseMeta) repairUgUsage(ctx Context, qtype uint32, usageMap map[uint64]*Summary, quotaMap map[uint64]*Quota) error {\n\tidType := \"uid\"\n\tif qtype == GroupQuotaType {\n\t\tidType = \"gid\"\n\t}\n\tif err := m.en.cleanUgUsage(ctx, qtype); err != nil {\n\t\treturn fmt.Errorf(\"clean %s quotas: %w\", idType, err)\n\t}\n\tif err := m.repairUsage(ctx, usageMap, quotaMap, qtype); err != nil {\n\t\treturn fmt.Errorf(\"set %s quota: %w\", idType, err)\n\t}\n\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 {","sourceCodeStart":1035,"sourceCodeEnd":1071,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/quota.go#L1035-L1071","documentation":"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.","triggerScenarios":"`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.","commonSituations":"Large filesystems hitting scan timeouts; metadata backend connectivity issues; concurrent metadata mutations confusing the scan; corrupted or inaccessible inode ranges.","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."],"exampleFix":"// before: scan fails under load\n$ juicefs quota check --uid 1000 /mnt/jfs\n// after: run when cluster quiet / backend healthy\n$ juicefs status sqlite3://test.db  # confirm healthy\n$ juicefs quota check --uid 1000 /mnt/jfs","handlingStrategy":"retry","validationCode":"// precheck engine health and skip check if the scan source is unavailable\nif _, err := m.en.doLoadQuotas(ctx); err != nil {\n    return fmt.Errorf(\"skip U/G quota check; engine unhealthy: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"err := checkUGUsage(ctx, repair, quotas)\nif err != nil && strings.Contains(err.Error(), \"scan global user group usage\") {\n    time.Sleep(30 * time.Second)\n    err = checkUGUsage(ctx, repair, quotas) // transient scan failures often clear\n}","preventionTips":["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."],"tags":["metadata","quota","scan","backend"],"backgroundTag":"database-query-failed","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"}