Troubleshooting Simulation Errors
When something goes wrong compiling or running your model, ARMOR shows an error overlay instead of a blank or frozen 3D view. The heading tells you when it failed:
- “Error Loading MuJoCo Model” — the model never started simulating at all. Something in the URDF, world, or mesh set failed to compile.
- “Error Simulating MuJoCo Model” — the model loaded and ran for a while, then the physics solver gave up mid-simulation.
Below the heading is a short, plain-language summary of what happened, and a collapsed Details section with MuJoCo’s own raw error text underneath it. Depending on the error, you’ll see some combination of these buttons:
| Button | What it does |
|---|---|
| Fix This | Opens the specific editor needed to resolve this error — shown only when ARMOR recognizes a direct fix. |
| Halve Timestep | Retries the simulation at half the current Timestep — shown for stability errors. |
| World Settings | Jumps to the World editor’s Timestep field for manual tuning. |
| Learn More | Opens this page at the section for that error. |
| Report Problem | Opens a pre-filled email to ARMOR support, for anything not covered here. |
Find your error’s heading below for what it means, why it happens, and how to fix it. The same pages are available inside the app: see Built-In Help and Ask.
Missing Mesh
What it means: The URDF references a mesh file — Missing mesh “X” (used by …) — that ARMOR can’t find anywhere in your project. The model still loads: links without their mesh show placeholder geometry, and the XML tab still shows the full URDF text. Simulation is blocked because MuJoCo needs real geometry to compute contacts and collisions, not a placeholder.
Why it happens: Usually an incomplete import — the URDF’s own package was downloaded or copied without one of its mesh files, a relative mesh path doesn’t match where the file actually landed, or the file was renamed after the URDF was written.
How to fix it:
- Re-import the robot’s folder from its original source, making sure the full
meshes/directory comes along with the URDF. - Or, if you only need to replace one file, open the affected link in the Links editor and set its Visual or Collision mesh via the asset picker — give the replacement file the exact same name the URDF expects.
Unreadable Mesh File
What it means: ARMOR found the mesh file, but couldn’t read it.
Why it happens: MuJoCo’s collision engine only understands OBJ, STL, and MSH mesh files natively. ARMOR auto-converts DAE, GLB, and USD/USDZ meshes into one of those three formats for you — this error means that conversion also failed, which almost always points to the source file itself being corrupt or truncated (a partial download, an export that didn’t finish) rather than an unsupported format.
How to fix it:
- Re-download or re-export the mesh from its original source.
- Open it in a 3D viewer or modeling tool outside ARMOR to confirm it’s intact before re-importing.
Invalid Inertia Tensor
What it means: A link’s inertia tensor isn’t physically possible. MuJoCo requires each principal moment to be no larger than the sum of the other two — the same triangle-inequality-style constraint real rigid bodies always satisfy.
Why it happens: Most often a manually entered or copied inertia tensor that doesn’t actually describe the link’s real mass distribution — for example, values copied from a different, more elongated link, or a placeholder tensor left over from an earlier edit.
How to fix it: Tap Fix This. It opens the Fix Inertia sheet for the exact link named in the error, showing each tensor value before and after the correction. Choose Confirm to apply it. To correct every affected link at once, use Fix All Inertias in the Links section of the robot editor. You can also edit the values yourself under Links → Inertial Properties if you know the correct mass distribution. See Mass and Inertia for the details.
Degenerate Collision Mesh
What it means: A collision mesh has effectively zero volume or surface area, or its triangles are wound inconsistently (some facing in, some facing out) — either way, MuJoCo can’t compute a sane inertia or contact surface from it.
Why it happens: Common with very thin, flat parts (sheet metal, a panel with negligible thickness) whose collision mesh was generated without any real depth, or a mesh exported with mixed/flipped face normals.
How to fix it:
- Toggle Has Inertial? on for the link under Links → Inertial Properties and enter mass and inertia values directly, bypassing MuJoCo’s geometry-based calculation entirely.
- Or repair the mesh in a 3D modeling tool — give a flat part a small amount of real thickness, and make sure its face winding is consistent — then re-import.
Zero-Size Primitive Shape
What it means: A box, cylinder, or sphere geometry — visual or collision — has one or more dimensions set to zero (a box with a zero-length side, a cylinder with zero radius).
Why it happens: Usually a typo or an unset field left at its default during manual editing, rather than anything in the original URDF.
How to fix it: Open the link in the Links editor, find the Visual or Collision section using the zero-sized shape, and correct its size, radius, or length field to a real, positive value.
Disconnected Joint Tree
What it means: Every link in a model has to be reachable from a single root through the joint tree. ARMOR lists the specific joint(s) responsible when this isn’t the case.
Why it happens: One of three things, each named explicitly in the error:
- A joint is missing its
parentorchildlink reference. - Two joints share the same name.
- A link is claimed as the child of more than one joint — giving it two parents, which makes the structure a graph rather than a tree.
How to fix it: Open the Joints editor and check each joint named in the error — reassign a missing parent or child link via its picker, rename one of a pair of duplicate joint names, or correct whichever joint is wrongly claiming a link that already belongs elsewhere. If the structure is badly tangled, re-importing a corrected URDF is often faster than fixing it joint by joint.
Zero-Length Joint Axis
What it means: A revolute, continuous, or prismatic joint’s axis vector is (0, 0, 0) — there’s no direction for it to rotate or slide along.
Why it happens: Almost always a hand-edited or auto-generated URDF where the <axis> element was left at its unset default instead of a real direction.
How to fix it: Open the joint in the Joints editor and set its Axis to a real unit vector matching the direction it should actually move in — (0, 0, 1) for a vertical hinge, (1, 0, 0) for one along X, and so on.
Joint Attached to the World Frame
What it means: A joint’s parent is the world frame directly rather than another link in the robot.
Why it happens: This is a structural issue ARMOR normally detects and repairs automatically during import — a robot’s joints should only ever connect its own links to each other. Seeing this error means that automatic repair didn’t catch this particular case.
How to fix it: There’s no editor fix to make here. Tap Report Problem and include the robot or URDF you loaded — this is a gap in ARMOR’s own import handling, not something wrong with your model.
Simulation Became Unstable
What it means: The model compiled and started running correctly, then the physics diverged — joint velocities or positions grew without bound rather than settling into believable motion.
Why it happens: Most often the simulation Timestep is too large for the model’s complexity. A robot with many links, a free-floating base, or dense contacts needs a smaller integration step than the default of 0.002 s (2 ms) — a 98-link free-base humanoid, for example, may need 0.001 s or smaller to stay stable.
How to fix it:
- Tap Halve Timestep to immediately retry at half the current step size — often enough on its own.
- Tap World Settings to open the Timestep field directly for manual tuning — see Worlds & Robot Placement for what it controls.
- If reducing the timestep doesn’t resolve it, check the model’s mass values, inertia tensors, and joint limits for anything unrealistic — an implausibly light link next to a heavy one, or conflicting joint limits, can destabilize a simulation at any timestep.
Solver Ran Out of Memory
What it means: MuJoCo’s internal solver exhausted the memory it allocates for contacts and constraints before it could finish a step.
Why it happens: Usually dense, high-polygon collision geometry — full visual meshes used directly as collision shapes across many links — or a very large multi-robot world with many simultaneous contacts.
How to fix it:
- Use simplified, lower-polygon meshes (or primitive shapes — box, cylinder, sphere) for collision geometry instead of your full visual meshes.
- Turn off collision entirely for links that don’t need realistic contact — decorative or purely cosmetic parts rarely do.
Other Errors
If your error doesn’t match any case above, tap Report Problem — it opens a pre-filled email to ARMOR support. Before sending, add:
- A one-line description of what you were doing when it happened (importing, editing, pressing Play).
- The robot or URDF involved, and where it came from.
- Anything in the Details text that looks unusual or specific to your model.
That’s usually enough for a new error case to get proper detection and guidance added here.
Reading the Details Text
The Details section shows MuJoCo’s own error message verbatim, not a rewritten or simplified version. That’s deliberate: MuJoCo’s own documentation, GitHub issues, and community threads all reference this exact wording, so keeping it intact is what makes it useful to search, and what makes a bug report filed through Report Problem actually actionable.