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

urdf_fix

urdf_inspect

Validation Categories

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 = False in import config.

Common Pitfalls

1. 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_mapping output.
2. 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.
3. Collision geometry affects performance: Missing collision geometry means no contact detection for that link. Add simplified collision meshes for physics-critical links.
4. 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.