microsoft/garnet · error · GarnetException

Maximum Vector Set allocations exceeded, cannot issue new co

Error message

Maximum Vector Set allocations exceeded, cannot issue new context

What it means

Thrown by NextVectorSetContext when a new Vector Set is being created and the internal context address space would exceed uint.MaxValue. Each context is addressed by an offset computed as contextMetadataIndex * 64 * ContextStep (ContextStep=8); when growing the contextMetadatas array would push that offset past uint.MaxValue, the store refuses to allocate. The code comments note this corresponds to roughly 8.3M Vector Sets per store and is treated as a hard capacity ceiling rather than a recoverable condition.

Source

Thrown at libs/server/Resp/Vector/VectorManager.ContextMetadata.cs:502

                            _ = dirtyContextMetadatas.Add(i);

                            return contextToRet;
                        }
                    }

                    // Today we limit ourselves to uint.MaxValue _contexts_ (ContextStep per Vector Set).
                    //
                    // If a new ContextMetadata would allow us to exceed that limit, fail.
                    //
                    // This is unlikely (~8.3M Vector Sets), so treated as an error.
                    //
                    // We could raise this to ulong.MaxValue by increasing reserved space on the DiskANN size, in which case
                    // the cause of failure would be the GC refusing to allocate a large enough contextMetadatas array.
                    var limitOfNewAllocation = ContextMetadata.OffsetForContextMetadata(contextMetadatas.Length) + (64 * ContextStep);
                    if (limitOfNewAllocation > uint.MaxValue)
                    {
                        throw new GarnetException("Maximum Vector Set allocations exceeded, cannot issue new context");
                    }

                    // All allocated contexts are full, allocate more space
                    var newContextMetadatas = new ContextMetadata[contextMetadatas.Length + 1];
                    contextMetadatas.AsSpan().CopyTo(newContextMetadatas);

                    contextMetadatas = newContextMetadatas;
                    startFrom = contextMetadatas.Length - 1;

                    _ = dirtyContextMetadatas.Add(startFrom);
                }
            }
        }

        /// <summary>
        /// For testing purposes, force a number of contexts to be allocated.
        /// 
        /// Contexts are not persisted at call time, but may be persisted after future operations.

View on GitHub (pinned to 951b0fc683)

Solutions

  1. Verify you are not leaking Vector Set keys (delete/VDROP unused sets so their contexts can be cleaned up) to stay far below the ~8.3M ceiling.
  2. Shard Vector Sets across multiple Garnet instances/databases (MaxDatabases) so no single store approaches the per-store context limit.
  3. If you genuinely need more, this is an architectural limit — file an issue upstream; the comment notes raising it to ulong would require reserving more space on the DiskANN size.
  4. Confirm via INFO or your own instrumentation how many live Vector Sets exist before assuming the limit is real rather than a context-reclamation bug.

Example fix

// before: one store holding unbounded vector sets
for (i in millions_of_tenants) vccreate($"vs:{i}"); // approaches ~8.3M ceiling

// after: shard tenants across logical databases / instances
var db = (tenantId % NumShards);
client.Select(db);
vccreate($"vs:{tenantId}");
Defensive patterns

Strategy: try-catch

Validate before calling

// Before heavy VCREATE loops, check how many live Vector Sets you already hold
// (track in your application layer, since contexts are per-store and not exposed as a count).
if (knownLiveVectorSetCount > 8_000_000) {
    throw new InvalidOperationException("Approaching per-store Vector Set ceiling (~8.3M); shard instead.");
}

Try / catch

try {
    await client.VAddAsync(key, vector, element);
} catch (GarnetException ex) when (ex.Message.Contains("Maximum Vector Set allocations exceeded")) {
    // Per-store capacity ceiling hit; shed load or shard rather than retry blindly.
    logger.LogError(ex, "Vector Set context ceiling reached on this store");
    throw;
}

Prevention

When it happens

Trigger: Creating a new Vector Set (e.g. the first VADD into a key that triggers VCREATE, or any operation that mints a fresh context) once the store already holds ~8.39M ContextMetadata blocks. The check is `OffsetForContextMetadata(contextMetadatas.Length) + (64 * ContextStep) > uint.MaxValue` evaluated at VectorManager.ContextMetadata.cs:499-502.

Common situations: Effectively unreachable in normal operation; would only appear in long-running multi-tenant systems that programmatically mint millions of distinct Vector Sets without ever deleting/reclaiming them, or in a test harness that loops VCREATE indefinitely.

Related errors

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