juicedata/juicefs · error

failed to load %q quotas: %w

Error message

failed to load %q quotas: %w

What it means

loadQuotas scans all enabled quota key prefixes ('QD','QU','QG') via scanValues; if the underlying KV scan itself fails (connection error, timeout, store error), the raw error is wrapped with the quota category name to show which quota type could not be loaded.

Source

Thrown at pkg/meta/tkv.go:3603

	quotaTypes := []struct {
		enabled bool
		prefix  string
		name    string
		quotas  map[uint64]*Quota
		decode  func(k string) uint64
	}{
		{format.DirStats, "QD", "dir", dirQuotas, func(k string) uint64 { return uint64(m.decodeInode([]byte(k[2:]))) }}, // skip prefix
		{format.UserGroupQuota, "QU", "user", userQuotas, func(k string) uint64 { return binary.BigEndian.Uint64([]byte(k[2:])) }},
		{format.UserGroupQuota, "QG", "group", groupQuotas, func(k string) uint64 { return binary.BigEndian.Uint64([]byte(k[2:])) }},
	}

	for _, qt := range quotaTypes {
		if !qt.enabled {
			continue
		}
		pairs, err := m.scanValues(ctx, m.fmtKey(qt.prefix), -1, nil)
		if err != nil {
			return nil, nil, nil, fmt.Errorf("failed to load %q quotas: %w", qt.name, err)
		}
		for k, v := range pairs {
			qt.quotas[qt.decode(k)] = m.parseQuota(v)
		}
	}

	return dirQuotas, userQuotas, groupQuotas, nil
}

func (m *kvMeta) cleanUgUsage(ctx Context, qtype uint32) error {
	if qtype != UserQuotaType && qtype != GroupQuotaType {
		return fmt.Errorf("invalid quota type: %d", qtype)
	}

	var prefix string
	if qtype == UserQuotaType {
		prefix = "QU"
	} else {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Check connectivity to the metadata engine and retry the mount/load operation
2. If using etcd with many quotas, reduce quota count or move to a store without iterator limits (Redis/MySQL/TiKV)
3. Inspect the wrapped inner error (%w) to identify the store-level cause and fix that first
4. Increase scan/request limits in the KV store configuration (e.g. etcd --max-request-bytes)

// health-check the metadata engine before loading quotas
if err := pingMetaEngine(metaURL); err != nil {
	return fmt.Errorf("metadata engine unreachable: %w", err)
}

quotaLoad := func() error { return loadQuotas(ctx) }
if err := backoff.Retry(quotaLoad, backoff.WithMaxRetries(3)); err != nil {
	// inspect wrapped store error: connectivity vs. scan limits
}

When it happens

Trigger: Loading quotas at mount/startup (or during quota usage aggregation) when the TKV client's scan/iterator fails — network partition, store unavailable, prefix too large hitting an iterator limit (etcd's range limit, for example).

Common situations: etcd range requests exceeding its response/transaction size limits with many quotas; TiKV/etcd connectivity problems at mount time; store-side timeouts under heavy load.

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

• scan global user group usage: %v
• scan global user group usage: %w
• invalid key %x
• invalid quota value: %v
• set total inodes: %w

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