Nav2 Error Codes

name: nav2-error-codes description: 'Interpret Nav2 error and result codes. Use when debugging navigation failures, handling planner/controller errors, or recovery logic.'

Nav2 Error Codes

Overview

Nav2 servers return integer error codes through their action results. These codes propagate from server → BT action node → BT blackboard → user code. Understanding them is essential for building robust recovery strategies.

Error Code Definitions

Planner Server Error Codes

Controller Server Error Codes

Behavior Server Error Codes

Error Flow Through the System

Planner/Controller plugin
  → Server action result (error_code integer)
    → BT action node reads result
      → Sets error_code on BT blackboard
        → BT error handling nodes check code
          → Recovery or abort

In the Behavior Tree

BT action nodes expose error_code_id to map server error codes to blackboard variables:

<ComputePathToPose goal="{goal}" path="{path}" planner_id="GridBased"
                   error_code_id="{compute_path_error_code}"/>

<FollowPath path="{path}" controller_id="FollowPath"
            error_code_id="{follow_path_error_code}"/>

The error_code_names parameter on the BT Navigator maps error code names to their integer values for BT condition checking:

bt_navigator:
  ros__parameters:
    error_code_names:
      - compute_path_error_code
      - follow_path_error_code

Recovery Based on Error Code

In the BT XML, you can check error codes to select appropriate recovery:

<RecoveryNode number_of_retries="3" name="NavigateRecovery">
  <PipelineSequence name="NavigateWithReplanning">
    <RateController hz="1.0">
      <ComputePathToPose goal="{goal}" path="{path}"
                         error_code_id="{compute_path_error_code}"/>
    </RateController>
    <FollowPath path="{path}" controller_id="FollowPath"
                error_code_id="{follow_path_error_code}"/>
  </PipelineSequence>
  <Sequence name="RecoveryActions">
    <!-- Clear costmaps if path planning failed -->
    <ClearEntireCostmap name="ClearGlobalCostmap"
                        server_timeout="5000" service_name="/global_costmap/clear_entirely_global_costmap"/>
    <ClearEntireCostmap name="ClearLocalCostmap"
                        server_timeout="5000" service_name="/local_costmap/clear_entirely_local_costmap"/>
    <!-- Spin if controller is stuck -->
    <Spin spin_dist="1.57" server_timeout="5000"
          error_code_id="{spin_error_code}"/>
    <!-- Backup if spin fails -->
    <BackUp backup_dist="0.3" backup_speed="0.1"
            error_code_id="{backup_error_code}"/>
    <!-- Wait as last resort -->
    <Wait wait_duration="5"/>
  </Sequence>
</RecoveryNode>

Interpreting Error Codes in Python

from nav2_simple_commander.robot_navigator import BasicNavigator, TaskResult

nav = BasicNavigator()
nav.goToPose(goal)

while not nav.isTaskComplete():
    pass

result = nav.getResult()
if result == TaskResult.FAILED:
    # The error_code is in the action result
    # Access via the underlying action client if needed
    nav.get_logger().error('Navigation failed')

For more detailed error information, use the action client directly:

from nav2_msgs.action import NavigateToPose
from rclpy.action import ActionClient

client = ActionClient(node, NavigateToPose, 'navigate_to_pose')
goal_handle = client.send_goal(goal_msg)
result = goal_handle.get_result()
error_code = result.result.error_code
# Map integer to meaning using the tables above

Error Code → Recovery Strategy Mapping

Common Diagnostic Pattern

When navigation repeatedly fails:

1. Check error_code in the action result
2. If TF_ERROR: run ros2 run tf2_tools view_frames to verify the TF tree
3. If NO_VALID_PATH or START/GOAL_OCCUPIED: visualize costmaps in RViz, look for phantom obstacles
4. If PATIENCE_EXCEEDED: check that the local costmap shows a clear path and the controller parameters allow sufficient velocity
5. If NO_VALID_CONTROL: the robot is surrounded by obstacles in the local costmap—check sensor data quality

Error Codes in Logging

Nav2 servers log error codes at WARN or ERROR level. Search logs for:

[controller_server]: Failed to find a valid control. Error code: 6
[planner_server]: No valid path found. Error code: 8