SixLabors/ImageSharp · error · ArgumentOutOfRangeException

maxDegreeOfParallelism

Error message

maxDegreeOfParallelism

What it means

The ParallelExecutionSettings constructor validates maxDegreeOfParallelism against the ParallelOptions.MaxDegreeOfParallelism contract: valid values are -1 (unbounded) or any positive integer. Passing 0 or any value less than -1 throws ArgumentOutOfRangeException.

Solutions

1. Pass -1 for unlimited parallelism instead of 0
2. Pass a positive integer (>= 1) for a fixed degree of parallelism
3. Normalize configuration values before constructing: value <= 0 && value != -1 -> clamp or map to -1

Example fix

// before
var settings = new ParallelExecutionSettings(parallelism, minPixels, allocator); // parallelism == 0
// after
int dop = parallelism == 0 ? -1 : parallelism;
var settings = new ParallelExecutionSettings(dop, minPixels, allocator);

if (maxDegreeOfParallelism is 0 or < -1)
    throw new ArgumentOutOfRangeException(nameof(maxDegreeOfParallelism), "Must be -1 or a positive integer.");

bool IsValidDop(int v) => v is -1 or > 0;

try { var s = new ParallelExecutionSettings(dop, minPixels, allocator); }
catch (ArgumentOutOfRangeException ex) { logger.LogError(ex, "Invalid MaxDegreeOfParallelism"); }

When it happens

Trigger: Constructing ParallelExecutionSettings with maxDegreeOfParallelism = 0 or <= -2, e.g. from user-supplied parallelism configuration or an environment-derived value that defaulted to 0.

Common situations: Parsing an int from config where 'auto' was mapped to 0 instead of -1; computing a thread count from Environment.ProcessorCount math that underflowed; copying a Task parallelism option of 0 meaning 'unspecified' into this API.

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.

Related errors

• Restart interval must be in [0..65535] range.
• No encoder was found for extension
• Unsupported color hex format.
• Source PCS to target PCS is not supported
• Source PCS is not supported

AI-assisted analysis of SixLabors/ImageSharp@59ce6af6fc (2026-09-13). Data as JSON: /api/errors/78a5c3ed28dc6bd5. Report an issue: GitHub.

Appendix: source

Thrown at src/ImageSharp/Advanced/ParallelExecutionSettings.cs:36

    /// <summary>
    /// Initializes a new instance of the <see cref="ParallelExecutionSettings"/> struct.
    /// </summary>
    /// <param name="maxDegreeOfParallelism">
    /// The value used for initializing <see cref="ParallelOptions.MaxDegreeOfParallelism"/> when using TPL.
    /// If set to <c>-1</c>, there is no limit on the number of concurrently running operations.
    /// </param>
    /// <param name="minimumPixelsProcessedPerTask">The value for <see cref="MinimumPixelsProcessedPerTask"/>.</param>
    /// <param name="memoryAllocator">The <see cref="MemoryAllocator"/>.</param>
    public ParallelExecutionSettings(
        int maxDegreeOfParallelism,
        int minimumPixelsProcessedPerTask,
        MemoryAllocator memoryAllocator)
    {
        // Shall be compatible with ParallelOptions.MaxDegreeOfParallelism:
        // https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.paralleloptions.maxdegreeofparallelism
        if (maxDegreeOfParallelism is 0 or < -1)
        {
            throw new ArgumentOutOfRangeException(nameof(maxDegreeOfParallelism));
        }

        Guard.MustBeGreaterThan(minimumPixelsProcessedPerTask, 0, nameof(minimumPixelsProcessedPerTask));
        Guard.NotNull(memoryAllocator, nameof(memoryAllocator));

        this.MaxDegreeOfParallelism = maxDegreeOfParallelism;
        this.MinimumPixelsProcessedPerTask = minimumPixelsProcessedPerTask;
        this.MemoryAllocator = memoryAllocator;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="ParallelExecutionSettings"/> struct.
    /// </summary>
    /// <param name="maxDegreeOfParallelism">
    /// The value used for initializing <see cref="ParallelOptions.MaxDegreeOfParallelism"/> when using TPL.
    /// If set to <c>-1</c>, there is no limit on the number of concurrently running operations.
    /// </param>
    /// <param name="memoryAllocator">The <see cref="MemoryAllocator"/>.</param>

View on GitHub (pinned to 59ce6af6fc)