ROS 2 reference

Nav2 navigation

Nav2 turns a goal pose into velocity commands by passing it down a chain of servers, and any link in that chain can quietly break. Most navigation bugs are not 'the robot is dumb'; they are one server failing while the rest keep waiting.

Nav2 is a pipeline of things that can fail

A goal pose enters at one end and /cmd_vel comes out the other, but in between sits a row of independent servers, each a lifecycle node. The BT Navigator runs a behavior tree that orchestrates everything. The Planner Server computes the global path (plugins like NavFn or Smac). The Controller Server follows that path locally and emits velocity (plugins like DWB or Regulated Pure Pursuit). The global and local Costmaps hold the world. The Behavior Server runs recoveries (spin, back up, wait). The Smoother and Velocity Smoother clean up the output. The lifecycle_manager brings all of them to Active.

Every one of those is a place navigation can break, and each fails in its own way. The skill is knowing which one failed before you start changing parameters.

Costmaps: where the world is wrong

A costmap is a grid of per-cell costs built from stacked layers. The three that matter most: Static (the map itself), Obstacle/Voxel (live sensor hits), and Inflation (a buffer of high cost grown around every obstacle so the robot keeps clearance). When navigation refuses to move, the costmap is usually the reason.

Inflation radius too large: the inflation buffer swallows the free space, so the goal or the robot itself lands in a lethal or inscribed cell and the planner refuses to plan.
Obstacle layer not clearing: phantom obstacles linger because raytrace or clearing is misconfigured, blocking paths that are actually open.
Wrong footprint or robot_radius: the robot believes it is a different size than it is, and either scrapes walls or cannot fit through gaps it should.

Planner vs controller: two different failures

The plannermakes a global path across the whole costmap. When it fails you get “failed to create plan”, and the cause is almost always the costmap: the start or goal sits in a lethal cell, or the free space is disconnected. No path exists, so nothing downstream runs.

The controller follows that path locally and emits velocity. When itfails, a global path exists in RViz but the robot sits and spins or twitches in place. The cause is local trajectory scoring: DWB critic weights, bad goal tolerances, or a path the robot’s kinematics simply cannot follow. Knowing which server failed tells you which half of the config to open.

The failures, and their tells

Robot spins in place, never drives forward: The controller cannot score a valid forward trajectory. DWB critic weights, xy/yaw goal tolerances, or a path the robot's kinematics cannot follow.
Goal rejected, planner never plans: Start or goal is in a lethal or inflated cell, or the costmap free space is disconnected. Usually inflation radius or an uncleared obstacle.
Nav2 never starts, no goal accepted: A lifecycle node failed to activate, so lifecycle_manager halted the bringup. See the lifecycle page.
Phantom obstacle blocks a clear route: The obstacle layer is marking but not clearing. Raytrace range or observation source misconfigured.
Path exists in RViz but robot ignores it: Controller frame or odom problem, or the controller plugin rejected the path. Check the local costmap frames and the controller log.
Robot loops through recoveries forever: The behavior tree keeps hitting a recovery branch because planning or control never succeeds. Fix the underlying costmap or controller cause, not the BT.

Debugging navigation

Watch the two plans

Start by asking whether each stage is producing output. If /plan is empty the planner failed; if /plan exists but /cmd_vel is silent the controller failed. And if the servers are not Active, nothing runs at all.

plans

# Global path from the planner
ros2 topic echo /plan --once

# Is the controller emitting velocity at all?
ros2 topic echo /cmd_vel

# Are the nav servers actually Active?
ros2 lifecycle get /planner_server
ros2 lifecycle get /controller_server

Look at the costmaps

The fastest costmap debugging is visual. Open RViz, add the global and local Costmap displays, and look for the goal or the robot sitting inside a colored (inflated or lethal) cell. That single glance answers most “why won’t it plan” questions. When you want the numbers, read the params directly.

costmap params

# Is inflation eating your free space?
ros2 param get /global_costmap/global_costmap inflation_radius
ros2 param get /global_costmap/global_costmap robot_radius

Fix it in a lab

These faults are not hypothetical. Cases like a robot that spins without ever driving, or a goal placed inside an inflated cell, are Nav2 bugs you diagnose in a live Gazebo session with the real stack running. Open the navigation path and find the broken server yourself.

Nav2 is a pipeline of things that can fail

Every one of those is a place navigation can break, and each fails in its own way. The skill is knowing which one failed before you start changing parameters.

Costmaps: where the world is wrong

Inflation radius too large: the inflation buffer swallows the free space, so the goal or the robot itself lands in a lethal or inscribed cell and the planner refuses to plan.

Obstacle layer not clearing: phantom obstacles linger because raytrace or clearing is misconfigured, blocking paths that are actually open.

Wrong footprint or robot_radius: the robot believes it is a different size than it is, and either scrapes walls or cannot fit through gaps it should.

Planner vs controller: two different failures

The failures, and their tells

Robot spins in place, never drives forward

The controller cannot score a valid forward trajectory. DWB critic weights, xy/yaw goal tolerances, or a path the robot's kinematics cannot follow.

Goal rejected, planner never plans

Start or goal is in a lethal or inflated cell, or the costmap free space is disconnected. Usually inflation radius or an uncleared obstacle.

Nav2 never starts, no goal accepted

A lifecycle node failed to activate, so lifecycle_manager halted the bringup. See the lifecycle page.

Phantom obstacle blocks a clear route

The obstacle layer is marking but not clearing. Raytrace range or observation source misconfigured.

Path exists in RViz but robot ignores it

Controller frame or odom problem, or the controller plugin rejected the path. Check the local costmap frames and the controller log.

Robot loops through recoveries forever

The behavior tree keeps hitting a recovery branch because planning or control never succeeds. Fix the underlying costmap or controller cause, not the BT.