juicedata/juicefs · error

unknown cache eviction policy: %q

Error message

unknown cache eviction policy: %q

What it means

JuiceFS's disk cache layer supports several eviction policies (none, LRU, etc.) selected via the CacheEviction config value. NewKeyIndex parses that string into a policy object; if the configured value does not match any known policy, construction fails with this error. It is a config validation error thrown at cache-store creation time.

Source

Thrown at pkg/chunk/cache_eviction.go:69

	evictionIter() func(yield func(key cacheKey, item cacheItem) bool)
}

func NewKeyIndex(config *Config) (KeyIndex, error) {
	switch config.CacheEviction {
	case EvictionNone:
		return &noneEviction{keys: make(map[cacheKey]cacheItem)}, nil
	case Eviction2Random:
		return &randomEviction{
			noneEviction: noneEviction{keys: make(map[cacheKey]cacheItem)},
			cacheExpire:  config.CacheExpire,
		}, nil
	case EvictionLRU:
		return &lruEviction{
			keys:    make(map[cacheKey]*lruItem),
			lruHeap: atimeHeap{},
		}, nil
	default:
		return nil, fmt.Errorf("unknown cache eviction policy: %q", config.CacheEviction)
	}
}

// noneEviction is a policy that does nothing.
type noneEviction struct {
	keys map[cacheKey]cacheItem
}

func (p *noneEviction) name() string {
	return EvictionNone
}

func (p *noneEviction) add(key cacheKey, item cacheItem) {
	p.keys[key] = item
}

func (p *noneEviction) remove(key cacheKey, staging bool) *cacheItem {
	item, ok := p.keys[key]

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Set CacheEviction to a supported value: check pkg/chunk/cache_eviction.go for accepted names (e.g. 'none', 'lru') and use one exactly (case-sensitive).
2. Remove the --cache-eviction flag entirely to use the default policy.
3. Check the JuiceFS version: `juicefs -V`; policy names may differ between versions, align config with that version's docs.
4. If the value comes from an environment template or operator config, fix it at the source so all clients receive a valid policy.

Example fix

// before
juicefs mount --cache-eviction lru2 sqlite3://test.db /mnt/jfs
// after
juicefs mount --cache-eviction lru sqlite3://test.db /mnt/jfs

allowed := map[string]bool{"none": true, "lru": true}
if !allowed[config.CacheEviction] {
    return fmt.Errorf("unsupported --cache-eviction %q; use one of: none, lru", config.CacheEviction)
}

When it happens

Trigger: Passing an unrecognized value in CacheEviction (e.g. via the --cache-eviction mount/CLI option or chunk store config) such as a typo ('lru2', 'random', case-sensitive mismatch) or a policy string from a newer/older JuiceFS version that this binary does not support.

Common situations: Copy-pasting mount options from documentation or another cluster running a different JuiceFS version; typos in cache-eviction flags in systemd units or KubernetesCSI configs; configuration migration where a policy name was renamed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid hour number
• illegal value for parameter 'ranger-service': " + serviceNam
• No sources given
• Source file " + normalizePath(src) + " is no
• Invalid ACL: multiple entries with same scope, type and name

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