A Nav2 behavior tree coordinates navigation actions, conditions and recovery behavior. It can replan, clear selected costmaps, wait, spin, back up or request another system response. The tree should translate known failures into bounded decisions; it should not turn every error into repeated robot motion.
Recovery quality depends on context. A planner error can justify a local repair near path computation, while a persistent localization or system failure may require cancellation and operator help. Preserve the original error before interventions overwrite it, and require measurable progress before another attempt consumes the retry budget.
Use this guide with the ROS 2 lifecycle recovery guide and Nav2 costmap guide. Test the tree with injected faults on the deployed robot configuration.
Use the tree as explicit navigation policy
Behavior trees make control flow visible through sequences, fallbacks, decorators, conditions and action nodes. Nav2 connects those nodes to planner, controller and behavior servers. The XML therefore becomes an operational policy that decides which failure is retried, repaired, escalated or returned to the caller.
The Nav2 behavior-tree documentation provides example trees that can be modified for an application. Treat examples as starting points. Add mission constraints, physical recovery permissions, retry limits and observability required by the actual vehicle and site.
Separate contextual recovery from system recovery
Contextual recovery sits close to the action that failed. A path-planning branch can clear a global costmap or try another planner, while a path-following branch can address a local costmap or controller condition. This proximity preserves useful fault identity and avoids broad intervention too early.
System recovery runs after narrower remedies are exhausted or when the failure is not local. It may wait for the environment, clear broader state, perform a permitted motion or end the navigation request. Define the transition between these levels from error class and evidence, not from a generic failure count alone.
| Failure evidence | Likely owner | Contextual response | Escalation example |
|---|---|---|---|
| No valid global path | Planner or global map | Recompute or targeted clear | Reject unreachable goal |
| Controller cannot progress | Local control or obstacle | Local clear or controlled wait | Cancel and hold |
| Pose invalid or jumping | Localization | Do not hide with map clear | Relocalize or request help |
| Server unavailable | Lifecycle or process | Check managed state | Supervisor recovery |
| Physical path obstructed | Environment | Wait or alternate route | Human intervention |
Understand RecoveryNode retry semantics
A RecoveryNode generally executes a primary child and invokes a recovery child after failure, with a configured number of retries. That structure is useful only when the recovery can change the condition that caused failure. Repeating the same inputs and state is merely delay and can produce repeated motion.
Document whether the retry count means total primary attempts or recovery cycles in the deployed implementation. Record each attempt number, error code and elapsed time. Bound both count and wall-clock duration because one slow action can exceed an operational limit even with a small retry count.
Preserve the first fault before recovery changes state
Clearing a map, restarting a server or moving the robot can erase evidence. Log the first failing action, server error, goal, path, pose, costmaps, transforms and relevant sensor age before the recovery branch mutates them. Correlate all records on a common clock.
Keep the final error and recovery history separately. If a spin later fails, it should not replace the original planner or localization fault in incident reporting. Operators need both the initiating cause and the last unsuccessful intervention.
Require progress between repeated attempts
A retry is justified when relevant state changed: a path became valid, an obstacle cleared, localization confidence recovered or the robot moved a meaningful distance. Define progress for each branch. A node returning success without changing the blocked condition should not reset the entire retry budget.
Use progress checkers for motion and branch-specific conditions for other work. Measure time and distance windows under low-speed operation so normal careful motion is not mistaken for a stall. Conversely, wheel rotation without base displacement is not navigation progress.
| Recovery action | Required permission | Progress evidence | Abort evidence |
|---|---|---|---|
| Wait | Area may clear safely | Obstacle or plan changes | Deadline exceeded |
| Clear costmap | Source can rebuild truth | Fresh observations arrive | Required source absent |
| Spin | Clearance supports rotation | New valid observation or path | Footprint risk or no change |
| Back up | Rear space verified | Exit from local trap | Unknown or blocked rear |
| Restart server | Fault class permits restart | Readiness becomes current | Repeated crash or invalid data |
Treat spin and backup as physical maneuvers
Spin and backup actions command real movement. Check footprint clearance, sensor coverage, payload stability, nearby people and site permissions before enabling them. A recovery maneuver acceptable on an empty research floor may be prohibited beside racks, stairs or shared workstations.
Set acceleration, velocity, distance and duration limits from the robot’s risk assessment. Verify cancel latency and stopping response. If rear sensing is insufficient, backup cannot be assumed safe merely because the forward controller reported no path.
Use costmap clearing only for known stale-state failures
Clearing may remove an observation that no longer corresponds to the environment, but it can also temporarily erase a true obstacle. Restrict clearing to layers and regions whose data can be reconstructed promptly from current sensors and whose source health is verified.
After clearing, wait for a declared refresh condition before planning or motion resumes. Record which layer and area were changed. Repeated clearing that briefly opens a path is evidence of a perception, transform or clearing defect, not a successful long-term recovery.
Choose replanning triggers deliberately
Replanning can run periodically, when a path becomes invalid, when the goal changes or when progress stalls. Excessive replanning consumes CPU and can cause route churn; sparse replanning can leave the controller following an obsolete path. Match the trigger to environmental dynamics and controller contract.
The Nav2 example trees include different replanning arrangements. Measure path age, computation time and controller behavior during replacement. Ensure that a newly computed path is validated and time-consistent before it overwrites the path currently being followed.
Map server errors to distinct tree branches
Planner, controller and behavior actions return structured results. Do not collapse every non-success state into one fallback. Distinguish cancellation, timeout, invalid goal, no path, failed progress, transform problems and server availability when the interfaces expose them.
Maintain a versioned error-to-policy table. Unknown error codes should take a conservative default path and remain visible in telemetry. When software upgrades add or alter result codes, regression tests should prove that each code still reaches the intended branch.
Coordinate cancellation and preemption
A new mission goal, operator stop or fleet reassignment can preempt navigation while recovery is running. Define which actions are halted, how long cancellation may take and whether a partially completed maneuver leaves the robot in a valid state. Do not start a new goal while old motion ownership remains ambiguous.
Test preemption inside waits, clears, spins, backups and server calls. Log the requester and final action results. A behavior tree that is correct without interruption can still issue stale motion if cancellation acknowledgment and command timeout are not coordinated.
Inject faults at every recovery level
Create repeatable tests for blocked plans, moving obstacles, sensor loss, stale transforms, invalid pose, server crash, rejected commands and failed recovery motion. For each case, verify selected branch, attempt count, elapsed time, physical output and final result returned to the mission layer.
Run tests under CPU and network load and with realistic payloads. Include compound failures, such as localization loss during a backup or controller restart while a new goal arrives. Recovery policy is credible only when it handles interruptions without hiding the initiating fault.
Release a bounded and observable recovery contract
Version the XML, plugin set, error mappings, retry budgets, maneuver permissions and timeout values together. Publish operator-readable state that says what failed, what recovery is active and what happens next. A generic Recovering label is insufficient during repeated physical motion.
Use a release checklist that emphasizes evidence and exit conditions.
- Keep contextual repairs near the action that failed.
- Bound attempts and wall-clock recovery time.
- Require measurable state change before retrying.
- Preserve the original fault and every intervention.
- Test cancellation and physical maneuver limits.
Frequently asked questions
What does a Nav2 behavior tree control?
It coordinates navigation actions, conditions, retries and recoveries by calling Nav2 servers according to an XML policy.
Should every failure clear both costmaps?
No. Clear only when stale map state is a supported hypothesis and current sources can reconstruct valid evidence.
How many recovery retries should be allowed?
Set a fault-specific count and time budget from operational risk and measured recovery effectiveness; there is no universal number.
Is spinning always a safe recovery?
No. It is a physical maneuver that requires clearance, sensing, motion limits and site permission.
What should be logged during recovery?
Preserve the first error, state snapshot, each intervention, progress evidence, attempt count, timing and final outcome.
Recovery Motion and Fault Boundary
Behavior-tree recovery can command robot motion and alter environmental state. It does not replace independent stopping, safeguarding or operator procedures required by the application.