What causes "the Mass of a Rigidbody cannot be negative." in stride3d/stride?

Only assign Mass >= 0 (0 typically means static/kinematic handling per engine conventions)

stride3d/stride · error · InvalidOperationException

the Mass of a Rigidbody cannot be negative.

Error message

the Mass of a Rigidbody cannot be negative.

What it means

Thrown by the RigidbodyComponent.Mass setter when a negative value is assigned. Mass is a physical property that must be non-negative (zero being used for special cases); a negative mass has no physical meaning and would corrupt the physics simulation, so the setter rejects it with an InvalidOperationException. The property is documented with DataMemberRange(0, 6) and user docs advising realistic point values.

Solutions

Only assign Mass >= 0 (0 typically means static/kinematic handling per engine conventions)
Clamp the value: rigidbody.Mass = Math.Max(0f, computedMass)
Check any config/UI producing mass values for negative ranges

Example fix

// before
rigidbody.Mass = -1f; // throws
// after
rigidbody.Mass = Math.Max(0f, computedMass);

Defensive patterns

Strategy: validation

Validate before calling

if (mass < 0f) throw new ArgumentOutOfRangeException(nameof(mass), "Mass cannot be negative.");
rigidbody.Mass = mass;

Try / catch

try { rigidbody.Mass = value; }
catch (InvalidOperationException) { /* clamp and retry */ rigidbody.Mass = 0f; }

Prevention

Clamp computed mass values with Math.Max(0f, m)
Restrict UI/config ranges to >= 0
Never use negative mass as a sentinel value

When it happens

Trigger: Setting rigidbody.Mass to any value < 0; computing mass from data that can go negative (e.g. difference calculations); deserializing configs with negative values.

Common situations: UI sliders or config files allowing negatives; script math producing negative mass; mass = -1 used as a sentinel for 'dynamic/auto' in other engines carried over incorrectly.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Physics/Elements/RigidbodyComponent.cs:83

        /// <value>
        /// true, false
        /// </value>
        /// <userdoc>
        /// Objects with higher mass push objects with lower mass more when they collide. For large differences, use point values; for example, write 0.1 or 10, not 1 or 100000.
        /// </userdoc>
        [DataMember(80)]
        [DataMemberRange(0, 6)]
        public float Mass
        {
            get
            {
                return mass;
            }
            set
            {
                if (value < 0)
                {
                    throw new InvalidOperationException("the Mass of a Rigidbody cannot be negative.");
                }

                mass = value;

                if (InternalRigidBody == null)
                {
                    return;
                }
                    

                var inertia = ColliderShape.InternalShape.CalculateLocalInertia(value);
                InternalRigidBody.SetMassProps(value, inertia);
                InternalRigidBody.UpdateInertiaTensor(); //this was the major headache when I had to debug Slider and Hinge constraint
            }
        }

        /// <summary>
        /// Gets the collider shape.

View on GitHub (pinned to 96fad776d2)