microsoft/garnet · error · InvalidDataException

Incompatible ClusterConfig version: expected {ClusterConfigV

Error message

Incompatible ClusterConfig version: expected {ClusterConfigVersion}, got {version}

What it means

After the length check, FromByteArray reads one version byte and compares it to ClusterConfigVersion (currently 1). A mismatch throws InvalidDataException with both expected and observed versions. This enforces binary compatibility of the gossip/replication config format across nodes — a node running a different Garnet build cannot join a cluster whose peers serialize a different config version.

Source

Thrown at libs/cluster/Server/ClusterConfigSerializer.cs:137

            ms.Position = segmentCountPosition;
            writer.Write(segmentCount);
            ms.Position = _position;
        }

        /// <summary>
        /// Deserialize config from byte array
        /// </summary>
        public static ClusterConfig FromByteArray(byte[] other)
        {
            var ms = new MemoryStream(other);
            var reader = new BinaryReader(ms);

            // Read and validate serialization format version
            if (other.Length < 1)
                throw new InvalidDataException("Invalid ClusterConfig payload: too short to contain a version");
            var version = reader.ReadByte();
            if (version != ClusterConfigVersion)
                throw new InvalidDataException($"Incompatible ClusterConfig version: expected {ClusterConfigVersion}, got {version}");

            var newSlotMap = DeserializeSlotMap(ref reader);

            int numWorkers = reader.ReadInt32();
            var newWorkers = new Worker[numWorkers];
            for (int i = 1; i < numWorkers; i++)
            {
                newWorkers[i].Nodeid = reader.ReadString();
                newWorkers[i].Address = reader.ReadString();
                newWorkers[i].Port = reader.ReadInt32();
                newWorkers[i].ConfigEpoch = reader.ReadInt64();
                newWorkers[i].Role = (NodeRole)reader.ReadByte();

                byte isNull = reader.ReadByte();
                if (isNull > 0)
                    newWorkers[i].ReplicaOfNodeId = reader.ReadString();

                newWorkers[i].ReplicationOffset = reader.ReadInt64();

View on GitHub (pinned to 951b0fc683)

Solutions

1. Run the same Garnet version (and thus the same ClusterConfigVersion) on all cluster nodes.
2. During rolling upgrades, follow the documented upgrade order so config versions stay compatible across the transition.
3. If loading a persisted config, regenerate it with the current build or migrate it to the supported version.

Example fix

// before — mismatched versions across nodes
node-A (v1.0, ClusterConfigVersion=1)  <--gossip-->  node-B (v2.0, ClusterConfigVersion=2)

// after — align all nodes to one Garnet version
// upgrade node-A to v2.0 so both serialize ClusterConfigVersion=2

// Peek the version without full deserialization to reject incompatible payloads early
if (!ClusterConfig.TryPeekVersion(payload, out var v) || v != ClusterConfig.ClusterConfigVersion)
    logger?.LogWarning("incompatible cluster config version {V}", v);

bool IsCompatibleVersion(byte[] p) => ClusterConfig.TryPeekVersion(p, out var v) && v == ClusterConfig.ClusterConfigVersion;

try { var config = ClusterConfig.FromByteArray(payload); }
catch (InvalidDataException ex) when (ex.Message.Contains("version")) { /* peer runs a different Garnet build; skip */ }

When it happens

Trigger: Two Garnet nodes with different ClusterConfig serialization versions exchange gossip or replicate a config; the receiver sees a version byte it does not understand. Also any caller deserializing a config produced by a different/older/newer build.

Common situations: Rolling upgrade where nodes run mixed Garnet versions during the transition; a config blob persisted by an older version loaded by a newer one; dev/test cluster with mismatched builds; cross-major-version incompatibility.

Related errors

• Invalid ClusterConfig payload: too short to contain a versio
• Gossip sample fraction should be in range [0,100]
• Getting handle in disposed device
• Failed to connect at {EndPoint}
• GarnetClientSession

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