stride3d/stride · error · InvalidOperationException

Attempted to call a Physics function that is avaliable only…

Error message

Attempted to call a Physics function that is avaliable only when the Entity has been already added to the Scene.

What it means

ApplyImpulse(Vector3) forwards the impulse to the underlying Bullet rigid body, which only exists after the entity is added to the scene and physics processed it. If InternalRigidBody is null it throws InvalidOperationException explaining that physics functions require the entity to be in the scene.

Solutions

Call ApplyImpulse only after the entity is added to the scene and physics is initialized (e.g. from Update or after PhysicsComponent processing)
Check rigidbody.InternalRigidBody != null before applying the impulse
Use a script Update/lifecycle method rather than construction/startup code

Example fix

// before
public MyScript() { rigidbody.ApplyImpulse(Vector3.UnitY * 10); } // InternalRigidBody null
// after
public override void Update() { rigidbody.ApplyImpulse(Vector3.UnitY * 10); } // entity in scene, body ready

Defensive patterns

Strategy: validation

Validate before calling

if (rigidbody.InternalRigidBody == null)
    throw new InvalidOperationException("Entity must be added to the scene before ApplyImpulse.");

Try / catch

try { rigidbody.ApplyImpulse(impulse); }
catch (InvalidOperationException) { /* defer until entity is in scene */ }

Prevention

Apply impulses only after entity is added to the scene
Defer physics calls to Update/post-physics callbacks
Never call physics APIs from constructors

When it happens

Trigger: Calling ApplyImpulse before the entity was added to a scene, or in the same frame before physics processing created the internal body; calling it after the entity was removed.

Common situations: Calling ApplyImpulse in a constructor, Start() before scene attachment, or in a script's initialization before the physics processor ran; applying impulses to entities not part of the scene.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

        }

        /// <summary>
        /// Gets the total torque.
        /// </summary>
        /// <value>
        /// The total torque.
        /// </value>
        public Vector3 TotalTorque => InternalRigidBody?.TotalTorque ?? Vector3.Zero;

        /// <summary>
        /// Applies the impulse.
        /// </summary>
        /// <param name="impulse">The impulse.</param>
        public void ApplyImpulse(Vector3 impulse)
        {
            if (InternalRigidBody == null)
            {
                throw new InvalidOperationException("Attempted to call a Physics function that is avaliable only when the Entity has been already added to the Scene.");
            }

            InternalRigidBody.ApplyCentralImpulse(impulse);
        }

        /// <summary>
        /// Applies the impulse.
        /// </summary>
        /// <param name="impulse">The impulse.</param>
        /// <param name="localOffset">The local offset.</param>
        public void ApplyImpulse(Vector3 impulse, Vector3 localOffset)
        {
            if (InternalRigidBody == null)
            {
                throw new InvalidOperationException("Attempted to call a Physics function that is avaliable only when the Entity has been already added to the Scene.");
            }

            InternalRigidBody.ApplyImpulse(impulse, localOffset);

View on GitHub (pinned to 96fad776d2)