SixLabors/ImageSharp · error · ArgumentException

Progressive scans must be in [2..64] range.

Error message

Progressive scans must be in [2..64] range.

What it means

JpegEncoder.ProgressiveScans is init-only validated to be between 2 and 64 inclusive and only applies to progressive JPEG encoding; out-of-range values throw ArgumentException at object-initializer time.

Solutions

1. Clamp/validate to [2..64] before assigning
2. For non-progressive output, leave ProgressiveScans unset instead of passing 1
3. Derive scan counts from ImageSharp's documented progressive scan script range
4. Validate config/query-string input before constructing the encoder

Example fix

// before
var encoder = new JpegEncoder { ProgressiveScans = scans }; // ArgumentException if scans < 2
// after
var encoder = new JpegEncoder { ProgressiveScans = Math.Clamp(scans, 2, 64) };

if (scans is < 2 or > 64) throw new ArgumentOutOfRangeException(nameof(scans), "ProgressiveScans must be in [2..64].");

static bool IsValidProgressiveScanCount(int s) => s is >= 2 and <= 64;

When it happens

Trigger: new JpegEncoder { ProgressiveScans = 1 } or > 64, commonly from a scan-count computed dynamically or copied from another encoder's scale where 1 scan means baseline.

Common situations: Assuming 1 scan is valid (baseline encoding uses no scan script — omit ProgressiveScans instead); generating scan counts from user input; porting settings from other encoders with different scan semantics.

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

• Quality factor must be in [1..100] range.
• Restart interval must be in [0..65535] range.
• Could not find any converter for JpegColorSpace
• Invalid ICC profile.
• color

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

Appendix: source

Thrown at src/ImageSharp/Formats/Jpeg/JpegEncoder.cs:67

    public bool Progressive { get; init; }

    /// <summary>
    /// Gets number of scans per component for progressive encoding.
    /// Defaults to <value>4</value>.
    /// </summary>
    /// <remarks>
    /// Number of scans must be between 2 and 64.
    /// There is at least one scan for the DC coefficients and one for the remaining 63 AC coefficients.
    /// </remarks>
    /// <exception cref="ArgumentException">Progressive scans must be in [2..64] range.</exception>
    public int ProgressiveScans
    {
        get => this.progressiveScans;
        init
        {
            if (value is < 2 or > 64)
            {
                throw new ArgumentException("Progressive scans must be in [2..64] range.");
            }

            this.progressiveScans = value;
        }
    }

    /// <summary>
    /// Gets numbers of MCUs between restart markers.
    /// Defaults to <value>0</value>.
    /// </summary>
    /// <remarks>
    /// Currently supported in progressive encoding only.
    /// </remarks>
    /// <exception cref="ArgumentException">Restart interval must be in [0..65535] range.</exception>
    public int RestartInterval
    {
        get => this.restartInterval;
        init

View on GitHub (pinned to 59ce6af6fc)