microsoft/FASTER · error · FasterException

Attempt to lock with unknown LockType

Error message

Attempt to lock with unknown LockType

What it means

OverflowBucketLockTable.TryLockManual only supports LockType.Shared and LockType.Exclusive; the switch's default arm throws FasterException for any other LockType value. This is an internal argument-validation guard on the lock table API.

Solutions

1. Pass exactly LockType.Shared or LockType.Exclusive to TryLockManual.
2. If the value comes from a variable, assert/validate it before locking: if (lt is not (LockType.Shared or LockType.Exclusive)) throw.
3. Check for uninitialized (default) enum fields that resolve to an unsupported value.

Example fix

// before
var lt = default(LockType);
lockTable.TryLockManual(keyCode, ref bucket, lt, context);
// after
var lt = LockType.Exclusive;
if (lt is not (LockType.Shared or LockType.Exclusive))
    throw new ArgumentOutOfRangeException(nameof(lt));
lockTable.TryLockManual(keyCode, ref bucket, lt, context);

if (lockType is not (LockType.Shared or LockType.Exclusive))
    throw new ArgumentOutOfRangeException(nameof(lockType), lockType, "Only Shared/Exclusive supported");
lockTable.TryLockManual(keyCode, ref bucket, lockType, context);

static bool IsSupportedLockType(LockType lt) => lt is LockType.Shared or LockType.Exclusive;

catch (FasterException ex) when (ex.Message.Contains("unknown LockType"))
{ logger.LogError(ex, "Bad LockType value passed to TryLockManual"); throw; }

When it happens

Trigger: Invoking TryLockManual (directly or via lock-orchestrator code) with a LockType other than Shared or Exclusive, e.g. LockType.None or a cast integer producing an undefined value.

Common situations: Custom locking/compaction code that passes an uninitialized or default LockType enum value, or enum arithmetic that yields an out-of-range value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 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/3e90f2d53ec1c0f8. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/Index/FASTER/Implementation/Locking/OverflowBucketLockTable.cs:69

        /// <inheritdoc/>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public unsafe bool TryLockManual(ref TKey key, ref HashEntryInfo hei, LockType lockType) 
            => TryLockManual(hei.firstBucket, lockType);

        /// <inheritdoc/>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public unsafe bool TryLockManual(long keyCode, LockType lockType) 
            => TryLockManual(GetBucket(keyCode), lockType);

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private unsafe bool TryLockManual(HashBucket* bucket, LockType lockType)
        {
            AssertLockAllowed();
            return lockType switch
            {
                LockType.Shared => HashBucket.TryAcquireSharedLatch(bucket),
                LockType.Exclusive => HashBucket.TryAcquireExclusiveLatch(bucket),
                _ => throw new FasterException("Attempt to lock with unknown LockType")
            };
        }

        /// <inheritdoc/>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public unsafe bool TryPromoteLockManual(long keyCode)
        {
            AssertLockAllowed();
            return HashBucket.TryPromoteLatch(GetBucket(keyCode));
        }

        /// <inheritdoc/>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public unsafe bool TryLockTransient(ref TKey key, ref HashEntryInfo hei, LockType lockType) 
            => lockType == LockType.Shared ? TryLockTransientShared(ref key, ref hei) : TryLockTransientExclusive(ref key, ref hei);

        /// <inheritdoc/>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]

View on GitHub (pinned to 321d872eab)