ProjekinAja. Robotics Stage 6 · Planning Deployment Lesson 6.5
● Stage 6 · Lesson 6.5

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.

⏱ ~22 min read 🧠 System architecture 🔧 Nav2 internals

🎯 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.

🔑 The mental model that unlocks Nav2 debugging

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:

Mission Client NavigateToPose action BT Navigator bt_navigator · bt_loop_duration=10 ms (up to 100 Hz) goal Planner Server ComputePathToPose plugin: NavfnPlanner / Smac Controller Server FollowPath plugin: DWB / TEB / MPPI Behavior Server Spin, BackUp, Wait… plugin: recoveries ComputePathToPose FollowPath recovery actions Costmap 2D global + local layers obstacle, inflation, static map global map local map cmd_vel TF2 tree, /map, /odom All components are lifecycle-managed ROS 2 nodes · goal feedback via ROS 2 actions
Nav2 architecture. The BT Navigator is the single entry point; it orchestrates ComputePathToPose (planner), FollowPath (controller), and recovery actions. Costmap 2D feeds both planner and controller with different map resolutions. Every box is a lifecycle-managed node — any one failing to activate silently breaks the pipeline.
1

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.

2

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.

3

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.

4

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.

5

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:

● Unconfigured → configure() → ● Inactive → activate() → ● Active (or → error) ● Error

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:

terminalwhat you see vs. what is happening
# 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.
⚠ The lifecycle manager does NOT stop launch on failure

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:

bashlifecycle state check
# 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.

nav2_goal.pyrclpy · sending a goal to Nav2
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.

💡 Action interface vs. topic: why it matters

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.

⚙ Interactive · Nav2 Pipeline Visualizer

Select a scenario, then step through the pipeline or inject a failure to see how the BT responds.

Goal In map frame PoseStamped BT Navigator ticks BT 10 Hz orchestrator Planner NavfnPlanner A* on grid Costmap global 2D 0.05 m/cell Path nav_msgs /Path Controller DWB 20 Hz FollowPath cmd_vel v, ω to base driver BT fallback → Behavior Server (Spin / BackUp) ↓ click any node to inspect · use scenario toggles to inject failures active node highlighted in stage color · error = red · recovery = gold
Hop latency (nominal — 5 Hz costmap update, 20 Hz controller)
Goal → BT tick
BT → Planner
Planner (A*)
Costmap query
Controller (DWB)
Total (first path)

Nominal navigation — all servers active

1. Goal received: the BT navigator action server accepts a NavigateToPose goal in map frame. It loads the default BT XML and starts ticking at up to 100 Hz (bt_loop_duration: 10 ms), with effective reactivity bounded by action server feedback at 5–10 Hz.

2. ComputePathToPose called: the BT's first action node calls the planner server. The planner queries the global costmap (A* on the occupied/free grid), returns a nav_msgs/Path in ~65 ms. The BT transitions to the FollowPath subtree.

3. FollowPath called: the controller server receives the path, starts publishing cmd_vel at 20 Hz. The local costmap updates at 5 Hz from LIDAR. The robot moves. BT feedback streams distance_remaining to the client.

4. Goal reached: the controller detects the robot is within goal_checker.xy_goal_tolerance (default 0.25 m) and yaw_goal_tolerance (default 0.25 rad). It returns success. The BT navigator returns success to the client. cmd_vel goes to zero.

Planner failure — path planning returns no solution

Injected fault: the goal is placed inside an inflated obstacle region. The global costmap marks the cell as LETHAL_OBSTACLE (cost = 254). NavfnPlanner cannot route to a LETHAL cell — it returns a PlannerException immediately.

BT response: the BT's ComputePathToPose action node returns FAILURE. The BT falls back to the recovery subtree: it calls ClearEntireCostmap (a behavior server action that resets transient obstacles) and retries planning. On second failure (after 2 retries), the BT navigator returns ABORTED to the client with result code FAILED_TO_PLAN.

Common misdiagnosis: operator assumes "the goal coordinates are wrong." More often, the inflation radius is too large for the environment's tight spaces (e.g., 0.4 m inflation in a 0.7 m doorway). Fix: reduce inflation_radius in the global costmap YAML, or use SmacPlannerHybrid which reasons about the robot's actual footprint during SE(2) search rather than relying on symmetric inflation.

Controller timeout — robot is stuck, no progress

Injected fault: the robot is blocked by a dynamic obstacle (a person standing still in the planned path). The DWB controller generates cmd_vel = 0 continuously because no local trajectory scores above the oscillation cost. The controller's progress_checker tracks distance traveled; if the robot moves less than min_distance (0.5 m default) in required_movement_time (10 s default), it raises a ControllerException.

BT response: ControllerException triggers BT fallback: (1) ClearLocalCostmap — wipes transient obstacle inflation in case the blocker is gone; (2) if still blocked after retry, calls Spin (rotates in place to update LIDAR view of environment); (3) on continued failure, calls BackUp to break potential symmetry; (4) final fallback: BT navigator returns ABORTED to client with result FAILED_TO_CONTROL.

Stuck recovery loop failure mode: if the BT's recovery subtree has no exit condition, the robot enters a Spin/BackUp loop indefinitely. This is the "recovery loop" failure: the robot oscillates between Spin and BackUp without making net progress, while the action remains RUNNING. Fix: add a max_retries decorator to the recovery subtree in the BT XML, and implement a Wait behavior at the end that signals a human operator.

Select a scenario, then click nodes to inspect each stage.

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:

BehaviorAction server nameWhat it doesWhen the BT calls itHidden 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
⚠ BackUp has no rear collision avoidance

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.

TopicRequired reliabilityDurabilityMismatch 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.
💡 Diagnose QoS mismatches quickly

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:

nav2_params.yamlYAML · FollowBot Nav2 parameters (abridged)
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
🔑 The allow_unknown parameter deserves its own warning

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

⚠ The lifecycle node that silently swallows every goal

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.

⚠ The costmap that stops updating after a parameter change

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.

⚠ The stuck recovery loop with no exit

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

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_navigator Nav2 component that loads a configurable Behavior Tree XML at startup and ticks it at 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 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_server Nav2 component that exposes the ComputePathToPose action. 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_server Nav2 component that exposes the FollowPath action. It generates cmd_vel at 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_radius within movement_time_allowance seconds, 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 /map topic — 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_vel directly — 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.

Next: behavior trees — the BT navigator ticks these, now learn what's inside →