microsoft/FASTER · error · FasterException

Unsupported number of simultaneous instances

Error message

Unsupported number of simultaneous instances

What it means

FastThreadLocal allocates a fixed-size slot array (shared across all FASTER instances in the process) and assigns each new instance a unique instance id via Interlocked CAS. When all slots are taken, the instance limit has been exceeded and the library throws FasterException. This guards a compile-time/process-wide maximum number of simultaneous FasterKV/FasterLog instances backed by this fast TLB mechanism.

Solutions

1. Dispose each FasterKV/FasterLog instance when no longer needed so slots can be reused.
2. Pool or singleton-cache store instances instead of creating one per operation/unit.
3. Split the workload across multiple processes if the fixed instance count is genuinely required.
4. Audit for leaked instances (finalizer warnings, untracked instances) with a memory profiler.

Example fix

// before
foreach (var tenant in tenants) stores[tenant.Id] = new FasterKV<long, byte[]>(settings); // unbounded
// after
using var store = storePool.GetOrCreate(tenant.Id); // pool bounded and instances disposed on eviction

if (activeStoreCount >= FastThreadLocal.MaxInstances)
    throw new InvalidOperationException("Too many live FASTER instances; dispose one first");

try
{
    var store = new FasterKV<long, byte[]>(settings);
    try { /* use */ } finally { store.Dispose(); }
}
catch (FasterException ex) when (ex.Message.Contains("Unsupported number of simultaneous instances"))
{
    logger.LogError(ex, "FASTER instance limit reached; pooling required");
    throw;
}

When it happens

Trigger: Constructing more FasterKV/FasterLog (or other epoch-backed) instances concurrently than the fixed slot count allows, without disposing/releasing earlier instances.

Common situations: Service code creating a FASTER store per request or per tenant without lifecycle management; leaking store instances in tests or DI containers; long-running processes that churn many stores.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

AI-assisted analysis of microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/c8cdd00f7d590bbf. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/Epochs/FastThreadLocal.cs:41

        private readonly int offset;
        private readonly int iid;

        private static readonly int[] instances = new int[kMaxInstances];
        private static int instanceId = 0;

        public FastThreadLocal()
        {
            iid = Interlocked.Increment(ref instanceId);

            for (int i = 0; i < kMaxInstances; i++)
            {
                if (0 == Interlocked.CompareExchange(ref instances[i], iid, 0))
                {
                    offset = i;
                    return;
                }
            }
            throw new FasterException("Unsupported number of simultaneous instances");
        }

        public void InitializeThread()
        {
            if (tl_values == null)
            {
                tl_values = new T[kMaxInstances];
                tl_iid = new int[kMaxInstances];
            }
            if (tl_iid[offset] != iid)
            {
                tl_iid[offset] = iid;
                tl_values[offset] = default(T);
            }
        }

        public void DisposeThread()
        {

View on GitHub (pinned to 321d872eab)