microsoft/garnet · critical · GarnetException

Range Index (preview) is not supported in cluster diskless m

Error message

Range Index (preview) is not supported in cluster diskless mode.

What it means

Thrown by GarnetServer.InitializeServer when both ReplicaDisklessSync and EnableRangeIndexPreview are enabled simultaneously. These features are incompatible: diskless replication does not materialize the RDB transfer on disk, but Range Index preview requires disk-backed snapshots. Garnet rejects this combination at startup rather than failing silently during replication.

Source

Thrown at libs/host/GarnetServer.cs:193

            {
                var red = "\u001b[31m";
                var magenta = "\u001b[35m";
                var normal = "\u001b[0m";

                Console.WriteLine($"""
                    {red}    _________
                       /_||___||_\      {normal}Garnet {version} {(IntPtr.Size == 8 ? "64" : "32")} bit; {(opts.EnableCluster ? "cluster" : "standalone")} mode{red}
                       '. \   / .'      {normal}Listening on: {(opts.EndPoints.Length > 1 ? opts.EndPoints[0] + $" and {opts.EndPoints.Length - 1} more" : opts.EndPoints[0])}{red}
                         '.\ /.'        {magenta}https://aka.ms/GetGarnet{red}
                           '.'
                    {normal}
                    """);
            }

            var clusterFactory = opts.EnableCluster ? new ClusterFactory() : null;

            if (opts.ReplicaDisklessSync && opts.EnableRangeIndexPreview)
                throw new GarnetException("Range Index (preview) is not supported in cluster diskless mode.");

            this.logger = this.loggerFactory?.CreateLogger("GarnetServer");
            logger?.LogInformation("Garnet {version} {bits} bit; {clusterMode} mode; Endpoint: [{endpoint}]",
                version, IntPtr.Size == 8 ? "64" : "32",
                opts.EnableCluster ? "cluster" : "standalone",
                string.Join(',', opts.EndPoints.Select(endpoint => endpoint.ToString())));
            logger?.LogInformation("Environment .NET {netVersion}; {osPlatform}; {processArch}", Environment.Version, Environment.OSVersion.Platform, RuntimeInformation.ProcessArchitecture);

            // Flush initialization logs from memory logger
            FlushMemoryLogger(this.initLogger, "ArgParser", this.loggerFactory);

            var customCommandManager = new CustomCommandManager();

            ThreadPool.GetMinThreads(out var minThreads, out var minCPThreads);
            ThreadPool.GetMaxThreads(out var maxThreads, out var maxCPThreads);

            bool minChanged = false, maxChanged = false;
            if (opts.ThreadPoolMinThreads > 0)

View on GitHub (pinned to 951b0fc683)

Solutions

1. If you need Range Index preview, disable ReplicaDisklessSync (set to false).
2. If you need diskless sync, disable EnableRangeIndexPreview (set to false).
3. Review your cluster replication strategy and choose one approach based on your operational needs.

Example fix

// before
var opts = new GarnetServerOptions
{
    EnableCluster = true,
    ReplicaDisklessSync = true,
    EnableRangeIndexPreview = true
};

// after: pick one
var opts = new GarnetServerOptions
{
    EnableCluster = true,
    ReplicaDisklessSync = false,
    EnableRangeIndexPreview = true
};

if (opts.ReplicaDisklessSync && opts.EnableRangeIndexPreview)
    throw new InvalidOperationException(
        "Range Index preview and diskless replication are mutually exclusive. " +
        "Disable one before starting the server.");

static bool AreReplicationOptionsValid(GarnetServerOptions opts) =>
    !(opts.ReplicaDisklessSync && opts.EnableRangeIndexPreview);

When it happens

Trigger: Configuring GarnetServerOptions with opts.ReplicaDisklessSync = true and opts.EnableRangeIndexPreview = true at the same time. The check is at GarnetServer.cs:192.

Common situations: Enabling Range Index preview on a cluster replica that was already configured for diskless sync; copying a config template that has both options set without understanding their interaction.

Related errors

• Gossip sample fraction should be in range [0,100]
• Option {fileType} not supported
• Checkpoint history unavailable, need full checkpoint for {en
• Failed to validate main store metadata at insertion
• RetrieveCheckpointFile: unexpected state{retStateType}

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