stride3d/stride · error · ArgumentOutOfRangeException

Specified argument was out of the range of valid values…

Error message

Specified argument was out of the range of valid values. (Parameter 'stretchDirection')

What it means

CalculateImageSizeFromAvailable's stretchDirection switch has a default branch that throws ArgumentOutOfRangeException for any StretchDirection outside DownOnly/UpOnly/Both. This guards against undefined enum values reaching the scaling math.

Solutions

Pass a valid StretchDirection (DownOnly, UpOnly, or Both)
Sanitize deserialized values with Enum.IsDefined before use
Default to StretchDirection.Both when the stored value is invalid

Example fix

// before
var dir = (StretchDirection)storedValue;
var size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, stretch, dir);
// after
var dir = Enum.IsDefined(typeof(StretchDirection), storedValue) ? (StretchDirection)storedValue : StretchDirection.Both;
var size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, stretch, dir);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(StretchDirection), stretchDirection))
    stretchDirection = StretchDirection.Both;

Type guard

static bool IsValidStretchDirection(StretchDirection d) => d == StretchDirection.DownOnly || d == StretchDirection.UpOnly || d == StretchDirection.Both;

Try / catch

try { size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, stretch, dir); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "stretchDirection") { size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, stretch, StretchDirection.Both); }

Prevention

Validate deserialized enum values before use
Keep enum definitions in sync across library versions
Default to StretchDirection.Both for unknown values

When it happens

Trigger: Passing an out-of-range cast value like (StretchDirection)7, or a default-initialized enum field whose 0 value is not a defined member; serializing/deserializing a bad numeric value.

Common situations: Config or XAML-like files storing integer stretch directions; version drift where enum members changed; uninitialized struct properties.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/0e46408e91120ad3. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.UI/ImageSizeHelper.cs:83

                default:
                    throw new ArgumentOutOfRangeException(nameof(stretchType));
            }

            // adjust the scales depending on the stretch directions
            switch (stretchDirection)
            {
                case StretchDirection.Both:
                    break;
                case StretchDirection.DownOnly:
                    desiredScale.X = Math.Min(desiredScale.X, 1);
                    desiredScale.Y = Math.Min(desiredScale.Y, 1);
                    break;
                case StretchDirection.UpOnly:
                    desiredScale.X = Math.Max(1, desiredScale.X);
                    desiredScale.Y = Math.Max(1, desiredScale.Y);
                    break;
                default:
                    throw new ArgumentOutOfRangeException(nameof(stretchDirection));
            }

            // update the desired size based on the desired scales
            desiredSize = new Vector3(idealSize.X * desiredScale.X, idealSize.Y * desiredScale.Y, 0f);

            if (!isMeasuring || !sprite.HasBorders)
                return desiredSize;

            // consider sprite borders
            var borderSum = new Vector2(sprite.BordersInternal.X + sprite.BordersInternal.Z, sprite.BordersInternal.Y + sprite.BordersInternal.W);
            if (sprite.Orientation == ImageOrientation.Rotated90)
                MemoryUtilities.Swap(ref borderSum.X, ref borderSum.Y);

            return new Vector3(Math.Max(desiredSize.X, borderSum.X), Math.Max(desiredSize.Y, borderSum.Y), desiredSize.Z);
        }
    }
}

View on GitHub (pinned to 96fad776d2)