stride3d/stride · error · ArgumentOutOfRangeException

ArgumentOutOfRangeException: orientation

Error message

ArgumentOutOfRangeException: orientation

What it means

The CapsuleColliderShape constructor switches on the requested ShapeOrientation (UpX/UpY/UpZ) to build the capsule and pick a debug rotation. An unrecognized orientation value reaches the default case and throws ArgumentOutOfRangeException("orientation").

Solutions

1. Pass only valid ShapeOrientation values: UpX, UpY, or UpZ.
2. Validate any int-to-enum cast with Enum.IsDefined before constructing the shape.
3. Fix the serialized asset/config field that holds the out-of-range orientation value.

Example fix

// before
var shape = new CapsuleColliderShape(radius, length, (ShapeOrientation)7);
// after
if (!Enum.IsDefined(typeof(ShapeOrientation), orientationValue))
    throw new ArgumentException($"Invalid orientation: {orientationValue}");
var shape = new CapsuleColliderShape(radius, length, ShapeOrientation.UpY);

if (!Enum.IsDefined(typeof(ShapeOrientation), orientation))
    throw new ArgumentException($"Invalid ShapeOrientation: {orientation}");

bool IsValidOrientation(ShapeOrientation o) => o is ShapeOrientation.UpX or ShapeOrientation.UpY or ShapeOrientation.UpZ;

try { var s = new CapsuleColliderShape(r, len, o); }
catch (ArgumentOutOfRangeException) { /* use default orientation */ }

When it happens

Trigger: Constructing new CapsuleColliderShape(...) with an invalid or uninitialized ShapeOrientation enum value (cast from an out-of-range int, or a config field holding a bad value).

Common situations: Orientation read from an asset/property serialized as an int that doesn't map to a defined enum member; upgrading Stride where enum members changed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• NotSupportedException: value
• is invalid type
• The target version is lower or equal to the start version.
• compilationContext should inherit from ICompilationContext
• The associated asset type does not have a public…

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

Appendix: source

Thrown at sources/engine/Stride.Physics/Shapes/CapsuleColliderShape.cs:68

                case ShapeOrientation.UpY:
                    shape = new CapsuleShape(radius, length)
                    {
                        LocalScaling = cachedScaling,
                    };
                    rotation = Matrix.Identity;
                    break;

                case ShapeOrientation.UpX:
                    shape = new CapsuleShapeX(radius, length)
                    {
                        LocalScaling = cachedScaling,
                    };
                    rotation = Matrix.RotationZ(MathF.PI / 2.0f);
                    break;

                default:
                    throw new ArgumentOutOfRangeException("orientation");
            }

            InternalShape = Is2D ? (CollisionShape)new Convex2DShape(shape) { LocalScaling = cachedScaling } : shape;

            DebugPrimitiveMatrix = Matrix.Scaling(new Vector3(DebugScaling)) * rotation;
        }

        public override MeshDraw CreateDebugPrimitive(GraphicsDevice device)
        {
            return GeometricPrimitive.Capsule.New(device, Length, Radius).ToMeshDraw();
        }

        public override Vector3 Scaling
        {
            get { return base.Scaling; }
            set
            {
                Vector3 newScaling;

View on GitHub (pinned to 96fad776d2)