The Nav2 Stack: Architecture, Lifecycle Nodes, and Failure Modes
Nav2 is an ecosystem of composable plugins — treat it as a black box and you will tune parameters blindly; understand its internals and you can diagnose any navigation failure in minutes.
🎯 By the end you'll understand
The five core Nav2 servers and how they compose into a navigation pipeline. Why lifecycle nodes exist and the specific silent failure that a misconfigured lifecycle activation causes. How goals flow through the action interface and what happens at each hop. Recovery behaviors and the behavior tree's role as the orchestrator. QoS policies for nav topics and why the wrong setting silently drops messages. The four most common Nav2 field failures and the diagnostic path to each one.
KEY INSIGHTNav2 is not a planner — it is a planner orchestration framework
The most insidious Nav2 failure mode looks like this: the robot receives a goal, the BT navigator logs "navigation started," the action server returns a running status — and nothing moves. No error. No timeout. Just silence. This is a lifecycle node that failed to activate.
Most tutorials teach Nav2 as "call NavigateToPose and watch the robot move." That works until it doesn't — and when it doesn't, nothing in your launch logs tells you why. Understanding Nav2's internals is not optional tuning knowledge; it is the difference between a 10-minute diagnosis and a 3-hour rabbit hole.
Nav2 is a collection of servers — each a lifecycle-managed ROS 2 node that exposes an action interface — connected by a Behavior Tree (BT) navigator that orchestrates them. The BT calls the planner server for a path, hands the path to the controller server for execution, and falls back to the behavior server when something goes wrong. Costmap 2D lives as a shared resource consumed by both planner and controller. If any server fails to transition to the active lifecycle state, the BT can still receive goals but cannot route them — it will sit silently in "running" state. This is the failure the lesson opens with.
HOW IT WORKSNav2 architecture: five servers, one orchestrator
Nav2 (Navigation2) is the ROS 2 successor to ROS 1's move_base. Rather than a monolithic node, it decomposes navigation into independently replaceable servers. Each server is a plugin host — you swap the underlying algorithm (e.g., A* vs. Smac Lattice for the planner) without touching the server's action interface. Here are the five core components:
BT Navigator (bt_navigator)
The single external action server clients talk to. It ticks a configurable Behavior Tree (a .xml file loaded at startup) with a target loop period of bt_loop_duration: 10 ms (up to 100 Hz); effective reactivity is bounded by action server feedback latency, which typically caps response at 5–10 Hz for long-running navigation actions. The BT orchestrates which servers get called, in which order, and what happens when they fail. The default BT calls ComputePathToPose, then FollowPath, and on failure falls back to recovery behaviors before retrying. You swap the BT file without changing any server.
Planner Server (planner_server)
Exposes a ComputePathToPose action. Receives a start pose and goal pose, queries the global Costmap 2D, and returns a nav_msgs/Path. The underlying algorithm is a plugin — default is NavfnPlanner (Dijkstra/A* on a 2D grid), alternatives include SmacPlannerHybrid (SE(2) A* with Dubin curves) for non-holonomic constraints. Planning typically takes 20–150 ms depending on map size and obstacle density.
Controller Server (controller_server)
Exposes a FollowPath action. Receives the global path and generates cmd_vel at the controller frequency (default 20 Hz). The underlying algorithm is a plugin — DWB (successor to DWA), TEB, or MPPI. The controller also queries the local Costmap 2D at the same frequency, so it can react to new obstacles that the global planner did not see. If the controller cannot make progress within a configurable timeout, it returns failure to the BT.
Behavior Server (behavior_server)
Exposes recovery action servers: Spin, BackUp, Wait, AssistedTeleop. The BT calls these when the planner or controller fails. Each behavior directly publishes cmd_vel while active — the controller server is bypassed during recovery. This means the behavior server does not query the costmap: it is the operator's responsibility to ensure recovery motions are safe in the deployment environment.
Costmap 2D (costmap_2d)
A layered 2D occupancy grid — each layer adds information (static map, LIDAR obstacle layer, sonar layer, inflation layer). The global costmap (fed to the planner) is typically low-frequency and large; the local costmap (fed to the controller) is high-frequency and small (e.g., 3×3 m rolling window). Costmap update frequency is the single most common Nav2 performance bottleneck: if the obstacle layer doesn't update fast enough, the controller drives into obstacles the LIDAR is already reporting.
CORE CONCEPTLifecycle nodes: why they exist and the silence they hide
Every Nav2 server is a lifecycle node — a ROS 2 node that implements the managed lifecycle state machine defined in rclcpp_lifecycle. The lifecycle exists to allow orchestrated, safe startup and shutdown. A Nav2 launch file calls nav2_lifecycle_manager, which transitions all nodes through:
Why does this matter for diagnosis? If any server's on_configure() callback fails — because a costmap parameter is malformed, a plugin shared library is missing, or a required topic doesn't exist yet — the node transitions to the error state silently. The lifecycle manager logs the failure, but if you miss that log line (and in a dense launch, it is easy to miss), you will see:
# What the action server reports when goal is sent: [bt_navigator] Received goal: navigate_to_pose [bt_navigator] Starting navigation... # What you DON'T see — the planner server is in error state, # its action server was never registered, the BT call hangs: [planner_server] on_configure failed: "plugin 'NavfnPlanner' not found" [lifecycle_manager] Node planner_server failed to configure - error state # The BT navigator sees no result from ComputePathToPose, # waits for the action timeout (default: 20 s), then fails. # From the client's perspective: action is RUNNING for 20 seconds, then ABORTED.
By default, nav2_lifecycle_manager in Humble logs a warning when a node fails to configure but continues starting the other nodes. The BT navigator reaches the active state. The planner server is in error state. The system looks alive — topics are visible in ros2 topic list, the action server shows up in ros2 action list — but any goal will silently timeout. Always check ros2 lifecycle list after launch to verify all nodes are in the active state before sending a goal.
The correct diagnostic command:
# List all lifecycle nodes and their current states ros2 lifecycle list # Expected healthy output: # /bt_navigator [active] # /controller_server [active] # /planner_server [active] <-- if this says [error], that's your bug # /behavior_server [active] # /map_server [active] # If a node is in error state, force a re-transition attempt: ros2 lifecycle set /planner_server configure ros2 lifecycle set /planner_server activate
HOW IT WORKSThe action interface: goal flow and feedback
Nav2's external interface is a ROS 2 action — the right abstraction for long-running tasks that need feedback and can be cancelled. The primary action is NavigateToPose, but Nav2 also exposes NavigateThroughPoses and FollowWaypoints.
from nav2_msgs.action import NavigateToPose from rclpy.action import ActionClient from geometry_msgs.msg import PoseStamped import rclpy class Nav2GoalSender(Node): def __init__(self): super().__init__('nav2_goal_sender') self._client = ActionClient(self, NavigateToPose, 'navigate_to_pose') def send_goal(self, x, y, yaw): goal = NavigateToPose.Goal() goal.pose = PoseStamped() goal.pose.header.frame_id = 'map' # MUST be map frame goal.pose.header.stamp = self.get_clock().now().to_msg() goal.pose.pose.position.x = x goal.pose.pose.position.y = y # orientation from yaw (simplified; use tf_transformations for real use) import math goal.pose.pose.orientation.z = math.sin(yaw / 2) goal.pose.pose.orientation.w = math.cos(yaw / 2) self._client.wait_for_server() future = self._client.send_goal_async( goal, feedback_callback=self.feedback_cb ) future.add_done_callback(self.goal_response_cb) def feedback_cb(self, feedback_msg): fb = feedback_msg.feedback self.get_logger().info( ff"distance remaining: {fb.distance_remaining:.2f} m" ) # feedback published at BT loop rate (up to 100 Hz, typically 5-10 Hz effective)
Three things to notice. First, the goal pose must be in the map frame — Nav2 will reject or silently misroute a goal in odom frame. This is the most common "my robot goes to the wrong place" cause when FollowBot's person-tracking node publishes a goal in odom frame during localization drift. Second, the action feedback gives distance_remaining (at BT loop rate, effectively 5–10 Hz bounded by action server latency) — useful for triggering a deceleration behavior as the robot approaches its target. Third, wait_for_server() blocks only until the BT navigator's action server is advertised; it does not check whether the underlying planner or controller servers are active. The lifecycle check above is still necessary.
Publishing to /goal_pose (which RViz 2 does when you click "2D Nav Goal") is a convenience shortcut — internally the BT navigator subscribes to this topic and converts it to an action goal. The feedback and result are discarded. For any programmatic use — FollowBot's mission node — use the action interface directly: you get result codes, feedback, and the ability to cancel mid-execution. The topic shortcut has no way to report "planner failed" to your code.
SEE ITNav2 pipeline visualizer — inject failures, watch the BT respond
Click through the Nav2 pipeline: from goal submission through the BT navigator → planner → costmap → path → controller → cmd_vel. Then inject a planner failure or a controller timeout and observe the BT's fallback to recovery behaviors. Each hop shows its representative latency. The worst outcome is not the one that crashes — it's the one that looks like it's working.
IN PRACTICERecovery behaviors: safety valve, not solution
Recovery behaviors exist to get the robot out of a dead end so planning can be retried. They are not a substitute for better planning. The Nav2 behavior server ships with four behaviors:
| Behavior | Action server name | What it does | When the BT calls it | Hidden cost |
|---|---|---|---|---|
| Spin | spin |
Rotate in place by a configurable angle (default 1.57 rad) | After controller timeout, to reacquire LIDAR view of the space | Rotates even if there is no room — can drag the robot into an obstacle if the environment is tight |
| BackUp | backup |
Drive backward by a configurable distance (default 0.15 m) | After Spin fails to unlock the situation | No rear-facing obstacle avoidance — the behavior server does not query the costmap during execution |
| Wait | wait |
Sit still for a configurable duration (default 5 s) | Terminal recovery when Spin and BackUp have both failed | If the obstacle is a person who will move, this is the right call. If it's a wall, it wastes time. |
| AssistedTeleop | assisted_teleop |
Accept manual velocity commands and filter them through the local costmap | Explicitly triggered via service call or BT node | Requires human operator presence; mixes autonomous and manual modes which can confuse state machines |
This is not a bug — it is a documented design choice. The behavior server publishes raw cmd_vel directly. It does not route through the controller server, which means the costmap is not consulted during recovery. A BackUp behavior issued in a narrow hallway can drive the robot directly into whatever is behind it. For FollowBot operating in populated indoor environments, always add a rear-facing ultrasonic sensor or implement a custom recovery plugin that checks the rear arc of the LIDAR scan before commanding backward motion.
CORE CONCEPTQoS for nav topics: the silent message loss that kills navigation
ROS 2's QoS system is more nuanced than ROS 1's TCP/IP topics. Nav2 has specific QoS requirements that, if mismatched, silently drop messages — the subscriber exists, the publisher exists, but data never arrives.
| Topic | Required reliability | Durability | Mismatch consequence |
|---|---|---|---|
/map |
RELIABLE | TRANSIENT_LOCAL | Nav2 never receives the map — costmap stays empty — planner fails on every goal. Classic "working in simulation but not on the real robot" issue when map_server QoS doesn't match. |
/tf, /tf_static |
BEST_EFFORT (/tf), RELIABLE (/tf_static) |
VOLATILE / TRANSIENT_LOCAL | TF lookup failures in the costmap: "waiting for transform map→base_link" infinite loop. Controllers cannot compute velocity. |
/scan |
BEST_EFFORT (acceptable) | VOLATILE | If the LIDAR driver publishes RELIABLE and the costmap subscribes BEST_EFFORT, no mismatch issue. Reverse causes drops. Symptom: costmap obstacle layer not updating despite LIDAR publishing. |
/cmd_vel |
RELIABLE | VOLATILE | BEST_EFFORT cmd_vel drops on a lossy USB serial bridge → robot misses velocity commands, lurches. Common on real hardware with cheap serial adapters. |
navigate_to_pose/_action/feedback |
RELIABLE | VOLATILE | Action feedback loss doesn't affect navigation, but your mission node won't receive distance_remaining updates — silent from client side. |
The DDS layer logs QoS incompatibilities at the INFO level (often buried). The reliable command: ros2 topic info /map --verbose — it shows publisher and subscriber QoS profiles side by side. Any mismatch on reliability or durability will cause silent topic death. The TRANSIENT_LOCAL durability on /map is load-bearing: it ensures that the costmap receives the map even if it subscribes after the map server finishes publishing the last message. Without transient-local durability on the map topic, a costmap that initializes 100 ms after the map server publishes will never receive the map — forever.
FOLLOWBOTConfiguring Nav2 for FollowBot
FollowBot's Nav2 configuration is the integration of everything built in Stage 4 (EKF localization), Stage 5 (SLAM occupancy grid), Lesson 6-2 (A* global planner), and Lesson 6-4 (DWA local planner) into a single composable stack. Here is the critical configuration file structure:
bt_navigator:
ros__parameters:
default_bt_xml_filename: "navigate_to_pose_w_replanning_and_recovery.xml"
odom_topic: "/odometry/filtered" # EKF output from Lesson 4-9
bt_loop_duration: 10 # ms — tick rate = 100 Hz max
planner_server:
ros__parameters:
planner_plugins: ["GridBased"]
GridBased:
plugin: "nav2_navfn_planner/NavfnPlanner"
tolerance: 0.5
use_astar: true # false = Dijkstra
allow_unknown: true # plan through unseen space (important for SLAM)
controller_server:
ros__parameters:
controller_frequency: 20.0 # Hz — matches DWB cycle
progress_checker_plugin: "progress_checker"
progress_checker:
plugin: "nav2_controller/SimpleProgressChecker"
required_movement_radius: 0.5
movement_time_allowance: 10.0
controller_plugins: ["FollowPath"]
FollowPath:
plugin: "dwb_core/DWBLocalPlanner"
max_vel_x: 1.2 # FollowBot hardware limit
min_vel_x: 0.0 # no reverse in follow mode
max_vel_theta: 1.5
acc_lim_x: 1.5 # matches L6-9 braking deceleration
acc_lim_theta: 2.5
local_costmap:
local_costmap:
ros__parameters:
update_frequency: 5.0 # Hz — LIDAR at 10 Hz, costmap at 5 Hz
publish_frequency: 2.0
global_frame: odom # local costmap in odom frame
robot_base_frame: base_link
rolling_window: true
width: 3
height: 3
resolution: 0.05
plugins: ["obstacle_layer", "inflation_layer"]
obstacle_layer:
plugin: "nav2_costmap_2d/ObstacleLayer"
observation_sources: scan
scan:
topic: /scan
obstacle_max_range: 8.0
raytrace_max_range: 8.0
inflation_layer:
plugin: "nav2_costmap_2d/InflationLayer"
inflation_radius: 0.35 # FollowBot radius 0.22 m + 0.13 m margin
cost_scaling_factor: 3.0
Setting allow_unknown: true in the planner allows NavfnPlanner to route through cells the SLAM map has not yet observed (marked as UNKNOWN, cost = 255 in the standard encoding). This is necessary for FollowBot: SLAM builds the map incrementally, so early in a session, large regions are unknown. Without allow_unknown: true, the planner will fail to route to any goal in unexplored space. The tradeoff: the robot may confidently drive into a wall that exists in reality but has not yet been mapped. During early SLAM sessions, combine this with a conservative inflation_radius and the LIDAR's local costmap as the primary collision-avoidance layer.
The FollowBot milestone for this stage: the full Nav2 stack is running. The BT navigator receives tracked-person positions from the perception system (published in map frame, updated at 5 Hz from Lesson 5-7's occupancy grid output), plans a global path from FollowBot's current pose to a point 1.2 m behind the tracked person, and hands it to the DWB controller for execution. The behavior tree orchestrates: detect person → navigate to tracked goal → maintain following distance → handle occlusion → recover. The full sim-to-real checklist is documented for each subsystem.
WEAKNESSWhere this bites
This is the most time-consuming Nav2 failure and the one you are least warned about. If the planner server's on_configure() fails (plugin not found, parameter missing, costmap initialization error), the lifecycle manager may still start the BT navigator. The BT navigator accepts your NavigateToPose goal, ticks its behavior tree, tries to call ComputePathToPose, and waits. The default action timeout for the planner call is configurable (wait_for_service_timeout in the BT XML) but often set to 20–30 seconds. From the client side: the action is RUNNING for 20–30 seconds, then ABORTED with a generic message. Diagnostic protocol: (1) run ros2 lifecycle list immediately after launch; (2) check that every Nav2 node is in state [active]; (3) if any is in [error], filter the launch log for that node's configure-phase output. This takes 30 seconds and saves hours.
Nav2's costmap layers are configured at startup and do not hot-reload. If you change inflation_radius in the YAML and re-launch with a stale parameter server (because use_sim_time or ros2 param load only partially succeeded), the costmap will use the old radius. The symptom: planner still fails on the narrow doorway after you "fixed" the inflation. Verify the live parameter: ros2 param get /local_costmap/local_costmap inflation_layer.inflation_radius. If this doesn't match your YAML, you have a parameter server mismatch — likely caused by launching with --ros-args -p overrides that conflict with the YAML file.
A common BT configuration mistake: the recovery subtree calls Spin → BackUp → retry planning, with no maximum retry count. If the environment physically prevents planning (e.g., the robot navigated into a cul-de-sac and the inflation radius makes the exit infeasible), the BT will cycle through Spin/BackUp indefinitely — the action remains RUNNING forever, batteries drain, operators are confused. The fix requires editing the BT XML to add a RetryUntilSuccessful or ReactiveFallback node with a max_retry_count attribute, and adding a terminal Wait node that calls a service to alert the operator. Nav2's default BTs ship without retry limits — this is a known gap, not an oversight to paper over.
KEY INSIGHTHow it connects
- 6.2 · Graph Search: A*, Heuristics, and Costmap Planning — the NavfnPlanner inside the Nav2 planner server is a thin wrapper around the A* algorithm on a costmap 2D grid; understanding that lesson's heuristic choice and grid encoding explains why the planner fails at narrow gaps.
- 6.4 · Local Planners: DWA, TEB, and Real-Time Obstacle Avoidance — the DWB controller plugin inside Nav2's controller server is the system implementation of the local planner theory covered there; the parameters in this lesson's YAML directly correspond to the DWA sampling bounds.
- 5.7 · Occupancy Grid Mapping: The Map Representation That Works — the global costmap's static map layer consumes exactly the occupancy grid produced by SLAM; the cell encoding (UNKNOWN=255, FREE=0, LETHAL=254) is the contract between SLAM and the planner.
- 4.9 · Multi-Sensor Fusion on FollowBot: Architecture and Covariance Design — the EKF localization output (
/odometry/filtered) is the odometry source the BT navigator and local costmap rely on to track the robot's pose in odom frame; covariance misconfiguration here propagates into costmap misalignment. - Next: 6.6 · Behavior Trees: Architecture, Ticks, and Reactive Mission Management → — the BT navigator in this lesson ticks a behavior tree; the next lesson opens the BT itself: node types, tick semantics, how the Nav2 default BTs are structured, and how to write a custom BT for FollowBot's person-following mission.
Nav2 is the integration layer where everything from Stages 4 and 5 becomes a working navigation system. The planner, controller, and costmap parameters you set here are directly constrained by FollowBot's sensor noise (Stage 4), map resolution (Stage 5), and kinematic limits (Stage 2). A Nav2 configuration that ignores those upstream constraints will produce a system that works in simulation and fails on hardware — the canonical sim-to-real gap for navigation stacks.
GLOSSARYKey terms
- Lifecycle node
- A ROS 2 node that implements the managed lifecycle state machine: Unconfigured → Inactive → Active (plus ErrorProcessing and Finalized). Nav2 uses lifecycle nodes for all servers to enable safe, orchestrated startup and shutdown. A node in the error state silently fails to process goals.
- BT Navigator
- The
bt_navigatorNav2 component that loads a configurable Behavior Tree XML at startup and ticks it at a target loop period ofbt_loop_duration: 10ms (up to 100 Hz). Effective reactivity is bounded by action server feedback latency, which typically caps observable response at 5–10 Hz for long-running navigation actions. It is the single action server that external clients (mission nodes) interface with; it orchestrates all other Nav2 servers internally. - Planner Server
- The
planner_serverNav2 component that exposes theComputePathToPoseaction. It is a plugin host — the underlying algorithm (NavfnPlanner, SmacPlannerHybrid, etc.) is swapped via YAML configuration without changing the server's interface. - Controller Server
- The
controller_serverNav2 component that exposes theFollowPathaction. It generatescmd_velat the controller frequency by invoking a pluggable local planner (DWB, TEB, MPPI) and checking progress via the progress checker plugin. - Costmap 2D
- A layered 2D occupancy grid in Nav2. The global costmap feeds the planner (large area, low update rate); the local costmap feeds the controller (small rolling window, high update rate). Layers are composable plugins: static map, obstacle, voxel, inflation. The inflation layer expands obstacles by the robot's radius to enable point-robot planning.
- Progress checker
- A plugin in the controller server that monitors whether the robot is making progress toward the goal. If the robot moves less than
required_movement_radiuswithinmovement_time_allowanceseconds, it raises a ControllerException, triggering the BT's recovery subtree. - TRANSIENT_LOCAL durability
- A ROS 2 QoS durability policy that causes the publisher to retain the last N messages and replay them to late-joining subscribers. Required for the
/maptopic — without it, any Nav2 component that subscribes after the map server's last publish never receives the map. - Recovery behavior
- A Nav2 behavior server action (Spin, BackUp, Wait, AssistedTeleop) invoked by the BT when the planner or controller fails. Recovery behaviors publish
cmd_veldirectly — they bypass the controller server and therefore do not use the costmap for collision avoidance.
ACTIVE RECALLCheck your understanding
Answer in your own words first, then reveal.
1A Nav2 goal is accepted (action status: RUNNING) but the robot never moves. No error logs appear from the BT navigator. What is the most likely root cause and what is the first command to run?›
The most likely cause is a lifecycle activation failure in one of the Nav2 servers — most commonly the planner server. The BT navigator reached the active lifecycle state and accepted the goal, but when it ticks the behavior tree and tries to call the planner server's ComputePathToPose action, the action server does not exist (because the planner server never activated). The BT waits for the action server to appear, consuming the full action timeout (often 20–30 s) before returning ABORTED. The first command to run is ros2 lifecycle list — this shows every Nav2 lifecycle node and its current state. Any node showing [error] or [inactive] is the root cause. Then filter the launch log for that node's configure-phase output to find the specific error (missing plugin, bad parameter, topic not available).
2What is the architectural difference between the planner server and the controller server, and why does Nav2 separate them?›
The planner server computes a collision-free global path from start to goal by querying the large, low-frequency global costmap. It is called once per goal (or on replanning events) and may take 20–200 ms. The controller server consumes that path and generates cmd_vel at high frequency (default 20 Hz) by querying the small, high-frequency local costmap. They are separated because their timing requirements are fundamentally different: the controller must run at hard-realtime rates to maintain stability; the planner can be slower and is computationally more expensive. Merging them would either slow the control loop to planning speed (dangerous) or require the planning algorithm to run within the control loop budget (often impossible). The separation also enables plugin independence: you can swap the planning algorithm without touching the controller, and vice versa.
3Why does Nav2's recovery behavior BackUp present a hazard even if the local costmap shows clear space behind the robot?›
The BackUp behavior publishes cmd_vel directly to the base driver, bypassing the controller server entirely. This means the local costmap is not consulted during the backward motion — even if the costmap shows clear space at the moment the behavior is triggered, any new obstacle that enters the robot's rear arc while it is backing up will not be detected. The costmap update happens asynchronously (e.g., at 5 Hz from LIDAR), and the BackUp behavior does not gate its cmd_vel on costmap updates. In practice, this means a person walking behind the robot while it is executing a BackUp recovery can be struck. The safe implementation for populated environments is a custom recovery plugin that checks the rear arc of the LIDAR scan directly before each velocity command, rather than relying on the pre-computed costmap state.
4The /map topic uses TRANSIENT_LOCAL durability. What failure does this prevent, and what happens if the costmap subscribes without TRANSIENT_LOCAL?›
TRANSIENT_LOCAL durability causes the map server to retain the last published map message and replay it to any subscriber that joins after the initial publish. This prevents a race condition: if Nav2's costmap initializes 50–200 ms after the map server has finished publishing (common in a dense launch), a normal VOLATILE subscriber would never receive the map — it missed the only publication. With TRANSIENT_LOCAL, the late-joining costmap immediately receives the retained message upon subscription. Without it, the global costmap remains empty (all cells UNKNOWN), the planner finds no navigable space, and every goal returns FAILED_TO_PLAN. This failure is particularly insidious on real hardware where launch timing is less deterministic than in simulation. The fix is ensuring both the map server publisher and all costmap subscribers declare TRANSIENT_LOCAL durability in their QoS profiles — they must match for the retained delivery to occur.