Troubleshooting Simulation Errors


This content is specific to Simscape™ Multibody™ First Generation software. First-generation features are slated to be deprecated and should be avoided.

About Simulation Errors

Simscape Multibody simulations can stop before completion with one or more error messages. This section discusses generic error types, and most errors and error-fixing strategies fall into broad categories. These groupings are reflected in the keywords occurring in the error messages. These sections summarize these groupings.

Data Validation Errors

Every numerical entry you make in a Simscape Multibody model must be a real numerical expression or MATLAB® equivalent. Spatial vectors are 3-vectors, such as [3 4 5]. Spatial tensors are 3-by-3 matrices, such as rotation matrices and the inertia tensor.


You can specify a two-dimensional curve in the Point-Curve Constraint block with 2-vectors.

Ground and Body Geometry Errors

Every machine must have at least one Ground block. Every Body block must have at least one Body CS, defined at the body's center of gravity (CG). You must directly or indirectly define the Body coordinate systems (CSs) of a machine relative to a Ground or to World. You cannot enter cyclic (circular) Body CS definitions. The Body CS definitions must separately satisfy these criteria in the Position and Orientation tabs of the Body dialog.

For example, defining CS3 relative to CS2, defining CS2 relative to CS1, then defining CS1 relative to CS3, results in a definition that is both cyclic and missing any reference to a Ground or World. You can break the cycle by referencing CS1 to a Ground or to World.

To be displayed in visualization, a Body must be connected to at least one Joint that is connected to the rest of the machine. You cannot visualize with equivalent ellipsoids a body whose principal inertial moments do not satisfy the triangle inequalities.

Joint Geometry Errors

The geometric configuration of joints, constraints, and drivers can conflict with assembly requirements and restrictions on certain blocks.

Assembly Tolerances Violated

Assembled joints must satisfy assembly tolerances on their connected Body CSs at all times. Disassembled joints assembled at model initialization must also satisfy assembly tolerances during the simulation. (See Controlling Machine Assembly.)

Zero Massless Connector Distance

The initial distance between two Body CS origins connected by a massless connector must be nonzero. The massless connector holds the distance between two Body CS origins constant during motion.

Composite Joints: Restrictions Among Primitives

Certain composite Joint blocks place restrictions on their primitive joint axes. For example, Bearing must have its prismatic axis P1 aligned to its third revolute axis R3.

Motion Inconsistency and Singularity Errors

Inconsistencies in motion arise from misapplication of constraints, drivers, and actuators, from conflicting stiction requirements, and incorrect simulation dimensionality.

Motion simulation errors often occur because of singularities or dividing by very small numbers. Simulink® solvers can integrate certain singularities, at a cost. Others, like loss of a degree of freedom (DoF), can be fatal. See Maintaining Constraints, Configuring a Simulink Solver, and Smoothing Motion Singularities and the Machine Environment block reference.

Zero Masses and Moments of Inertia

A body moving on a prismatic axis must have nonzero mass if you actuate it with forces. A body rotating about a revolute axis or pivoting about a spherical must have nonzero inertial moments about the axis or pivot if you actuate it with torques. If you want a massless rigid body, consider using a Massless Connector from the Joints/Massless Connectors sublibrary.


You can use point bodies (nonzero mass but zero moments) in Simscape Multibody models, if the connected revolute axes and spherical pivots are dislocated from the body. Although the moments are zero about a point body's CG, the displacement of the body from the axis or pivot shifts the moments from zero to nonzero values.

Alignment of Primitives — Coincidence of Identical Bodies

Within a single Joint block, two distinct prismatic axes or two distinct revolute axes should never align during the simulation. If either occurs, a translational or rotational DoF is lost, and the simulation cannot determine the subsequent motion. An example of such singularities is “gimbal lock.” Two of the three revolute primitive axes in the Gimbal block become parallel, reducing the number of independent DoFs in the Joint from three to two.

Two or more physically identical bodies (having the same masses and inertia tensors) should never coincide in space.

No Degrees of Freedom

Your machine cannot move if it has no degrees of freedom. Each Constraint, Driver, and motion-actuating Actuator block you add to a machine reduces the number of independent DoFs. (See Counting Model Degrees of Freedom) Cure such errors by removing one or more of these blocks from your machine, until you have at least one independent DoF.

Incorrect Machine Dimensionality

You cannot run a three-dimensional machine with a simulation restricted to two dimensions. See Choosing Your Machine's Dimensionality.

Redundant Constraints

Some constraints can restrict what another constraint is already restricting. If redundant constraints are present and in conflict, fix these errors by identifying and removing the redundancies. If the simulation misidentifies one or more redundant constraints, adjust the redundant constraint tolerance. See Maintaining Constraints.

Violated Constraints

Some machine motions or simulations might not be able to maintain assembly tolerances at a particular simulation step while simultaneously satisfying the constraints. One or more joints might become disassembled. Any one of these conditions leads to errors.

You can correct this situation in several ways. First, identify the joint, constraint, or driver causing the error and examine its physical configuration when the error occurs to isolate the conflict. Then try any combination of these steps:

  • Decrease the Simulink solver tolerances or the step size.

  • Switch to a more robust Simulink solver.

  • Decrease the constraint solver tolerances.

  • Increase the redundant constraint tolerance.

  • Switch to the machine precision constraint solver.

  • Increase the assembly tolerances.

See Maintaining Constraints and Configuring a Simulink Solver.

Conflicting Actuators

You cannot put more than one actuator on a joint primitive.


You can simultaneously place an initial condition actuator and a force/torque actuator on a joint primitive.

The Joint Stiction Actuator block does accept an input signal for nonfrictional forces/torques, which the block adds to the stiction.

Sticky Joints in Conflict

If your machine has two or more stiction-actuated (“sticky”) joints, a conflict among them can put the simulation into an infinite loop and prevent determination of the machine motion. Or one locked joint can prevent the other joints, sticky or not, from moving. The machine stops moving.

For example, one sticky joint becomes unlocked and requires the other to lock, which then requires the first to lock.

Remove these conflicts by removing one or more stiction actuators or by changing the Joint Stiction Actuator locking thresholds.

Analysis Mode Errors

Certain restrictions apply to the analysis modes presented in Choosing an Analysis Mode. Consult individual analysis modes for more:

Was this topic helpful?