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 'stretchType')

What it means

ImageSizeHelper.CalculateImageSizeFromAvailable switches on stretchType and its default branch throws ArgumentOutOfRangeException for any value outside the defined StretchType enum. This is an exhaustive-match guard protecting the scale computation.

Solutions

Pass a valid StretchType: None, Uniform, UniformToFill, or Fill (as supported by your Stride version)
Validate/normalize the enum value before calling the helper and fall back to a known value
Fix deserialization so unknown values map to a default instead of being cast blindly

Example fix

// before
var size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, (StretchType)rawInt, dir);
// after
var stretch = Enum.IsDefined(typeof(StretchType), rawInt) ? (StretchType)rawInt : StretchType.Uniform;
var size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, stretch, dir);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(StretchType), stretchType))
    stretchType = StretchType.Uniform;

Type guard

static bool IsValidStretch(StretchType s) => s == StretchType.None || s == StretchType.Uniform || s == StretchType.UniformToFill || s == StretchType.Fill;

Try / catch

try { size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, stretch, dir); }
catch (ArgumentOutOfRangeException ex) { logger.LogWarning("Invalid {Param}, falling back to Uniform", ex.ParamName); size = ImageSizeHelper.CalculateImageSizeFromAvailable(avail, ideal, sprite, StretchType.Uniform, dir); }

Prevention

Validate enum values from config/serialization with Enum.IsDefined
Never cast raw integers to enums without checking
Prefer switch-based mapping to a safe default value

When it happens

Trigger: Passing a StretchType value not handled by the switch (e.g. an undefined enum cast like (StretchType)99), or an enum field defaulting to 0 when 0 is not a defined member in the current Stride version.

Common situations: Loading a StretchType from config/serialization where the numeric value is out of range; enum values changed between library versions; uninitialized struct fields defaulting to an unmapped value.

Related errors

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

Appendix: source

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

            {
                case StretchType.None:
                    desiredScale = Vector2.One;
                    break;
                case StretchType.Uniform:
                    desiredScale.X = desiredScale.Y = Math.Min(desiredScale.X, desiredScale.Y);
                    break;
                case StretchType.UniformToFill:
                    desiredScale.X = desiredScale.Y = Math.Max(desiredScale.X, desiredScale.Y);
                    break;
                case StretchType.FillOnStretch:
                    // if we are only measuring we prefer keeping the image resolution than using all the available space.
                    if (isMeasuring)
                        desiredScale.X = desiredScale.Y = Math.Min(desiredScale.X, desiredScale.Y);
                    break;
                case StretchType.Fill:
                    break;
                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));
            }

View on GitHub (pinned to 96fad776d2)