majiayu000 URDF Validator & Fixer
Validate and fix URDF files before importing into Isaac Sim. Catches USD naming violations, duplicate materials, unbounded joint limits, missing inertial properties, and broken mesh references — problems that otherwise cause silent import failures.
Workflow
Follow this sequence for best results:
Phase 1: Inspect
Get a structural overview of the robot model.
urdf_inspect(file_path="/path/to/robot.urdf")
Review: link/joint counts, kinematic tree, mass distribution, mesh files.
Phase 2: Validate
Check for all known issues.
urdf_validate(file_path="/path/to/robot.urdf")
Review: issues by severity (error > warning > info) and category.
Phase 3: Fix
Auto-fix what can be fixed.
urdf_fix(
file_path="/path/to/robot.urdf",
output_path="/path/to/robot_fixed.urdf"
)
The original file is never modified. Check name_mapping in the result — if links or joints were renamed, downstream code (controllers, configs) needs updating too.
Phase 4: Re-validate
Confirm fixes resolved the issues.
urdf_validate(file_path="/path/to/robot_fixed.urdf")
Expect zero errors for fixed categories. Remaining warnings (e.g., missing collision geometry, package:// URIs) may need manual attention.
Tool Reference
urdf_validate
| Parameter | Type | Default | Description |
|---|---|---|---|
file_path |
str | None | Path to URDF file |
urdf_string |
str | None | URDF XML as string |
categories |
list[str] | all | Filter: usd_naming, materials, joint_limits, inertial, collision, mesh_references |
min_severity |
str | "info" | Minimum: error, warning, info |
urdf_fix
| Parameter | Type | Default | Description |
|---|---|---|---|
file_path |
str | None | Path to URDF file |
urdf_string |
str | None | URDF XML as string |
output_path |
str | auto | Output file path (default: *_fixed.urdf) |
fix_categories |
list[str] | all | usd_naming, materials, joint_limits, inertial |
default_mass |
float | 0.1 | Default mass (kg) for missing inertial |
default_inertia |
float | 0.001 | Default diagonal inertia value |
max_joint_position |
float | 2π | Replace ±inf position limits |
max_joint_velocity |
float | π | Default velocity limit (rad/s) |
max_joint_effort |
float | 100.0 | Default effort limit (Nm) |
urdf_inspect
| Parameter | Type | Default | Description |
|---|---|---|---|
file_path |
str | None | Path to URDF file |
urdf_string |
str | None | URDF XML as string |
Validation Categories
| Category | What it checks | Auto-fixable? |
|---|---|---|
usd_naming |
Hyphens, dots, spaces, leading digits in link/joint/material names | Yes — renames + updates all references |
materials |
Duplicate definitions with different RGBA, missing textures, JPEG warnings | Yes — deduplicates by appending suffix |
joint_limits |
Infinite limits, missing effort/velocity, missing <limit> element |
Yes — clamps to configurable defaults |
inertial |
Missing <inertial>, zero/negative mass, zero inertia tensor |
Yes — adds configurable defaults |
collision |
Visual geometry without corresponding collision geometry | No — requires manual modeling |
mesh_references |
Nonexistent mesh files, package:// URIs |
No — mesh files must exist on disk |
Isaac Sim Tips
- USD naming is critical: Isaac Sim converts URDF names to USD prim paths. Hyphens, dots, and spaces cause silent failures or mangled paths.
- Inertial is required: Links without
<inertial>may be silently skipped or cause physics instability. - Joint limits matter: Infinite limits can cause solver divergence. Isaac Sim may clamp them internally but the behavior is undefined.
package://URIs won't resolve: Isaac Sim doesn't have ROS package resolution. Convert to relative or absolute paths.- Fixed joints get merged: By default Isaac Sim merges fixed joints. If you need them separate, set
merge_fixed_joints = Falsein import config.
Common Pitfalls
- Renaming breaks downstream code: After USD naming fixes, joint names change. Update your controller configs, ROS topics, and any code referencing joint names by checking the
name_mappingoutput. - Default inertial values are placeholders: The auto-fix adds small default values to prevent crashes. Replace them with actual CAD-derived values for accurate simulation.
- Collision geometry affects performance: Missing collision geometry means no contact detection for that link. Add simplified collision meshes for physics-critical links.
- Mesh paths are relative to URDF location: When moving a fixed URDF to a different directory, mesh references may break. Keep the URDF and mesh directories together.
End-to-End Verification
After fixing, verify the import works in Isaac Sim:
/path/to/isaacsim/python.sh scripts/verify_urdf_isaac_sim.py \
--original /path/to/robot.urdf \
--fixed /path/to/robot_fixed.urdf
This script imports both URDFs headless, checks prim paths, joints, articulation, and runs physics steps to verify stability.