microsoft/garnet · error · Exception

Read cache requires storage tiering to be enabled

Error message

Read cache requires storage tiering to be enabled

What it means

The read cache is a caching layer over the on-disk (tiered) portion of the hybrid log, so it only has meaning when storage tiering is enabled. GetSettings rejects --readcache without --storage-tier because without a device-backed log there is nothing for the read cache to cache; records would already be memory-resident.

Source

Thrown at libs/server/Servers/GarnetServerOptions.cs:761

            DeviceFactoryCreator ??= new LocalStorageNamedDeviceFactoryCreator(
                deviceType: DeviceType,
                ioBackend: DeviceIoBackend,
                numCompletionThreads: DeviceCompletionThreads,
                throttleLimit: DeviceThrottleLimit > 0 ? DeviceThrottleLimit : null,
                logger: logger);
            if (DeviceType == DeviceType.Native && OperatingSystem.IsLinux())
                logger?.LogInformation("Using device type {deviceType} (io-backend={ioBackend}, completion-threads={ct}, throttle-limit={tl})", DeviceType, DeviceIoBackend, DeviceCompletionThreads, DeviceThrottleLimit > 0 ? DeviceThrottleLimit.ToString() : "device-default");
            else
                logger?.LogInformation("Using device type {deviceType} (throttle-limit={tl})", DeviceType, DeviceThrottleLimit > 0 ? DeviceThrottleLimit.ToString() : "device-default");

            if (LatencyMonitor && MetricsSamplingFrequency == 0)
                throw new Exception("LatencyMonitor requires MetricsSamplingFrequency to be set");

            // Read cache related settings
            if (EnableReadCache)
            {
                if (!EnableStorageTier)
                    throw new Exception("Read cache requires storage tiering to be enabled");
                kvSettings.ReadCacheEnabled = true;

                if (ReadCachePageCount != 0)
                    kvSettings.ReadCachePageCount = ReadCachePageCount;

                kvSettings.ReadCachePageSize = 1L << ReadCachePageSizeBits();
                kvSettings.ReadCacheMemorySize = ParseSize(ReadCacheMemorySize, out _);

                if (kvSettings.ReadCacheMemorySize > 0)
                {
                    var pageCount = kvSettings.ReadCacheMemorySize / kvSettings.ReadCachePageSize;
                    if (kvSettings.PageCount > pageCount)
                        logger?.LogInformation("[Store] Warning: Read cache overriding specified PageCount of {kvSettingsReadCachePageCount} with smaller page count calculated from LogMemorySize limit divided by PageSize: {pageCount}", kvSettings.ReadCachePageCount, pageCount);

                    var bufferSize = NextPowerOf2(pageCount);
                    logger?.LogInformation("[Store] Read cache enabled with {LogPages} log pages in memory, of which {pageCount} are initially allocated", PrettySize(bufferSize), pageCount);
                    logger?.LogInformation("[Store] Read cache Log memory size limit of {LogMemorySize} will be enforced", PrettySize(kvSettings.ReadCacheMemorySize));
                }

View on GitHub (pinned to 951b0fc683)

Solutions

1. Enable storage tiering too: add --storage-tier (and typically --logdir / --memory appropriately).
2. If you do not need disk-backed storage, drop --readcache; the in-memory log already serves reads.

Example fix

# before (fails)
garnet-server --readcache

# after
garnet-server --storage-tier --logdir /data/garnet --readcache --readcache-memory 1g

if (options.EnableReadCache && !options.EnableStorageTier) {
    throw new InvalidOperationException("EnableReadCache requires EnableStorageTier");
}

When it happens

Trigger: Starting with --readcache (EnableReadCache) true but --storage-tier (EnableStorageTier) false. Thrown at GarnetServerOptions.cs:760-761.

Common situations: Enabling read cache expecting it to work as a generic L1 cache; forgetting the storage-tier prerequisite when copying a config snippet.

Related errors

• Read Cache Log Memory size or PageCount must be specified
• MutablePercent must be between 10 and 95
• Store Log Memory size or PageCount must be specified
• Index size {IndexMemorySize} should not be less than index m
• LogDir specified without enabling tiered storage (UseStorage

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/b66d8f050ce20d66. Report an issue: GitHub.