What causes "set quota usage for file(%s), please repair it later" in juicedata/juicefs?

Run `juicefs quota --set ...` or the quota repair flow after fixing the underlying cause so usage is recalculated.

set quota usage for file(%s), please repair it later

Error message

set quota usage for file(%s), please repair it later

What it means

Raised by baseMeta.calcDirQuotaUsage when recalculating a directory's quota usage fails partway — most commonly because GetSummary on some file/inode returned a non-zero status. The wrap message includes the path of the file at which the calculation failed and explicitly tells the operator to repair quota usage later, because the quota accounting for that subtree is now incomplete/inaccurate.

Source

Thrown at pkg/meta/quota.go:683

		MaxInodes:  quota.MaxInodes,
		UsedSpace:  -1,
		UsedInodes: -1,
	})
	if err != nil {
		return err
	}
	if created && qtype == DirQuotaType {
		return m.calcDirQuotaUsage(ctx, Ino(key), dpath, strict)
	} else if scan && (qtype == UserQuotaType || qtype == GroupQuotaType) {
		return m.ScanUserGroupUsage(ctx)
	} else {
		return nil
	}
}

func (m *baseMeta) calcDirQuotaUsage(ctx Context, ino Ino, dpath string, strict bool) error {
	wrapErr := func(e error) error {
		return errors.Wrapf(e, "set quota usage for file(%s), please repair it later", dpath)
	}

	var sum Summary
	if st := m.GetSummary(ctx, ino, &sum, true, strict); st != 0 {
		return wrapErr(st)
	}

	_, err := m.en.doSetQuota(ctx, DirQuotaType, uint64(ino), &Quota{
		UsedSpace:  int64(sum.Size) - align4K(0),
		UsedInodes: int64(sum.Dirs+sum.Files) - 1,
		MaxSpace:   -1,
		MaxInodes:  -1,
	})
	if err != nil {
		return wrapErr(err)
	}
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Run `juicefs quota <meta-url> <path> --set ...` or the quota repair flow after fixing the underlying cause so usage is recalculated.
Unwrap the error to identify the exact file (path is embedded in the message) and inspect/repair that inode's metadata.
Check for concurrent modification (deletion/renames) during recalculation and re-run when the tree is quiet.
Verify metadata engine consistency; restore from a metadata backup if usage counters are corrupt.

Defensive patterns

Strategy: try-catch

Validate before calling

// Before enabling quotas, verify the tree summarises cleanly:
var s Summary
if st := m.GetSummary(ctx, rootIno, &s, true, false); st != 0 {
    // resolve summary errors before recalculating quotas
}

Type guard

inner := stderrors.Unwrap(err) // reveals the per-file status behind the wrap

Try / catch

if err := calcDirQuotaUsage(ctx, ino, dpath, true); err != nil {
    logger.Warnf("%v; schedule quota repair", err)
    // queue repair: juicefs quota <meta> <path> check
}

Prevention

Run quota checks (`juicefs quota ... check`) regularly to catch drift early.
Avoid heavy concurrent modifications while recalculating quota usage.
Enable quotas on a quiet tree; schedule recalcs off-peak.
Restore quota counters from metadata backup if corruption is suspected.

When it happens

Trigger: Calling code that recalculates directory quotas (quota repair/reload, e.g. after enabling dir quotas or running `juicefs quota`) when m.GetSummary(ctx, ino, &sum, true, strict) returns a non-zero status for some inode under the directory, or a later per-file usage update fails — wrapErr is invoked with the path of the offending file.

Common situations: Enabling directory quotas on a large tree where an underlying file fails to summarize (e.g. deleted concurrently, metadata inconsistent); quota usage drift after crashes; corrupted dir stat counters discovered during strict checks.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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