Nav2 YAML Parameter Structure

Source: ros2-copilot-skills Nav2 params structure skill

Why This Matters

Nav2 configuration is infamous for files that are valid YAML but wrong ROS 2 configuration. The pain comes from node naming, child-node costmaps, and plugin namespaces all being meaningful at once.

Distilled Takeaways

• The doubled costmap namespace is a consequence of child-node naming, not a typo.
• Plugin aliases in lists must match the nested parameter keys exactly.
• Launch-time rewriting is part of normal Nav2 configuration, especially for use_sim_time and BT file overrides.
• Node-name remapping can silently invalidate a parameter file if the top-level YAML keys no longer match.
• Most Nav2 YAML bugs are structure bugs, not algorithm bugs.

Practical Guidance

• Validate indentation and node names before touching controller or planner parameters.
• Treat parameter-file structure as part of bringup architecture.
• Keep one clear canonical navigation YAML file per robot configuration.
• Use rewritten YAML intentionally and always convert types when launch arguments drive boolean or numeric values.

Corroborating References

• Nav2 configuration guide
• ROS 2 launch and parameter guides

When to Read the Original Source

Go to the original skill when you want full hierarchy examples, RewrittenYaml explanation, and explicit mistake cases for indentation, namespace mismatch, and plugin-key mismatches.