dotnetcore/CAP · error · ArgumentException

worker Id can't be greater than

Error message

worker Id can't be greater than {MaxWorkerId} or less than 0

What it means

An argument sanity check in SnowflakeId's Initialize: the workerId supplied (from SnowflakeIdOptions or auto-detection) falls outside the legal range 0..MaxWorkerId (10 bits, i.e. 0–1023). Worker ids must uniquely identify each process within that bit budget; anything larger would collide with the timestamp/sequence bits, so ArgumentException is thrown during id-generator construction.

Solutions

  1. Set CAP.SnowflakeId.WorkerId (SnowflakeIdOptions) to a value between 0 and 1023 that is unique per running instance.
  2. For multi-node deployments, assign worker ids via configuration/deployment environment or a coordination service rather than hard-coding the same value everywhere.
  3. Leave WorkerId unset to let CAP auto-generate one from the machine's MAC address or a random value.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at src/DotNetCore.CAP/Internal/ISnowflakeId.Default.cs:118 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of dotnetcore/CAP@e52b8508e5 (2026-09-14). Data as JSON: /api/errors/2ea76d01f462c561. Report an issue: GitHub.

Appendix: source

Thrown at src/DotNetCore.CAP/Internal/ISnowflakeId.Default.cs:118

    {
        var currentWithSequence = ++_timestampAndSequence;
        var current = currentWithSequence >> SequenceBits;
        var newest = GetNewestTimestamp();

        if (current >= newest) Thread.Sleep(5);
    }

    /// <summary>
    /// Common method for initializing <see cref="SnowflakeId"/>
    /// </summary>
    /// <param name="workerId"></param>
    /// <exception cref="ArgumentException"></exception>
    private void Initialize(long workerId)
    {
        InitTimestampAndSequence();
        // sanity check for workerId
        if (workerId is > MaxWorkerId or < 0)
            throw new ArgumentException($"worker Id can't be greater than {MaxWorkerId} or less than 0");

        WorkerId = workerId << (TimestampBits + SequenceBits);
    }

    /// <summary>
    /// get newest timestamp relative to twepoch
    /// </summary>
    /// <returns></returns>
    private static long GetNewestTimestamp()
    {
        return DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() - Twepoch;
    }
}

internal static class Util
{
    /// <summary>
    /// auto generate workerId, try using mac first, if failed, then randomly generate one

View on GitHub (pinned to e52b8508e5)