microsoft/FASTER · error · FasterException

Invoke Iterate() on a client session (ClientSession), or…

Error message

Invoke Iterate() on a client session (ClientSession), or use store.Iterate overload with Functions provided as parameter

What it means

This parameterless/store-level Iterate overload is intentionally dead: it is marked [Obsolete] and its body unconditionally throws FasterException. FASTER removed direct store iteration; iteration must go through a client session so user IFunctions (checksums, concurrent reads) are supplied. Any call reaches this throw immediately.

Solutions

1. Create a client session and call its Iterate: fht.For Functions... .NewSession Functions and session.Iterate(...).
2. Use the store.Iterate overload that takes IFunctions/ICompactionFunctions parameters.
3. Remove references to the obsolete overload (compiler CS0618 warning points at it).

Example fix

// before
using var iter = store.Iterate();
// after
using var session = store.For(new Functions()).NewSession<Functions>();
using var iter = session.Iterate();

// Do not call store.Iterate() at all; resolve the session-based API instead.
using var session = store.For(new Functions()).NewSession<Functions>();
using var iter = session.Iterate();

static bool IsObsoleteStoreIterate(System.Reflection.MethodInfo m) =>
    m.Name == nameof(FasterKV<int,int>.Iterate) && m.IsDefined(typeof(ObsoleteAttribute), false);

catch (FasterException ex) when (ex.Message.Contains("Invoke Iterate() on a client session"))
{ throw new NotSupportedException("Use session.Iterate() instead of store.Iterate()", ex); }

When it happens

Trigger: Calling store.Iterate() (or store.Iterate(untilAddress)) on a FasterKV instance directly, e.g. code written against pre-session FASTER APIs or samples copied from old blog posts.

Common situations: Upgrading FASTER from an older version where store.Iterate worked; writing a one-off scan/dump tool without creating a ClientSession.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Out of order message within session
• Unexpected status of SubscribeKV
• Cannot use BlittableParameterSerializer with non-blittable…
• The inner list is full!
• The list is empty!

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

Appendix: source

Thrown at cs/src/core/Index/FASTER/FASTERIterator.cs:60

                return false;

            long numRecords = 1;
            bool stop = false;
            for ( ; !stop && iter.PushNext(ref scanFunctions, numRecords, out stop); ++numRecords)
                ;

            scanFunctions.OnStop(!stop, numRecords);
            return !stop;
        }

        /// <summary>
        /// Iterator for all (distinct) live key-values stored in FASTER
        /// </summary>
        /// <param name="untilAddress">Report records until this address (tail by default)</param>
        /// <returns>FASTER iterator</returns>
        [Obsolete("Invoke Iterate() on a client session (ClientSession), or use store.Iterate overload with Functions provided as parameter")]
        public IFasterScanIterator<Key, Value> Iterate(long untilAddress = -1) 
            => throw new FasterException("Invoke Iterate() on a client session (ClientSession), or use store.Iterate overload with Functions provided as parameter");

        /// <summary>
        /// Iterator for all (distinct) live key-values stored in FASTER
        /// </summary>
        /// <param name="compactionFunctions">User provided compaction functions (see <see cref="ICompactionFunctions{Key, Value}"/>).</param>
        /// <param name="untilAddress">Report records until this address (tail by default)</param>
        /// <returns>FASTER iterator</returns>
        [Obsolete("Invoke Iterate() on a client session (ClientSession), or use store.Iterate overload with Functions provided as parameter")]
        public IFasterScanIterator<Key, Value> Iterate<CompactionFunctions>(CompactionFunctions compactionFunctions, long untilAddress = -1)
            where CompactionFunctions : ICompactionFunctions<Key, Value> 
            => throw new FasterException("Invoke Iterate() on a client session (ClientSession), or use store.Iterate overload with Functions provided as parameter");
    }

    internal sealed class FasterKVIterator<Key, Value, Input, Output, Context, Functions> : IFasterScanIterator<Key, Value>
        where Functions : IFunctions<Key, Value, Input, Output, Context>
    {
        private readonly FasterKV<Key, Value> fht;
        private readonly FasterKV<Key, Value> tempKv;

View on GitHub (pinned to 321d872eab)