Configuring recovery behaviors

1. Engineering problem

When the planner or the controller fails, Nav2 runs recovery behaviours: clearing stale costmap obstacles, rotating, waiting or backing up. They help only if they are safe at the robot’s location and change something that matters.

2. When is this needed?

• Navigation aborts in narrow or busy places.
• Adding a new recovery or removing an unsafe one.
• Reviewing the safety of recoveries.

3. Selection and design decisions

From the default behaviour tree (jazzy, read 2026-11-06): the main tree is a RecoveryNode with number_of_retries="6"; planning (at 1 Hz) and path following each have a context recovery (clear the relevant costmap once if the error suggests it would help); when a failure persists, a RoundRobin runs these in turn: clear local and global costmaps, Spin by 1.57 rad, Wait 5 s, BackUp 0.30 m at 0.15 m/s; GoalUpdated interrupts recoveries. The behaviour server (default parameters) provides spin, backup, drive_on_heading, assisted_teleop and wait with cycle_frequency: 10.0 and simulate_ahead_time: 2.0.

4. Advantages and disadvantages

• More recoveries raise success rate and risk; remove those that are unsafe for the robot (no rear sensor, no room to spin).
• More retries keep trying and delay a call for help.
• Use the collision checks of the behaviours (simulate_ahead_time) and keep them on.

5. Requirements and constraints

• Every recovery is safe at the robot’s size and sensing.
• After the last retry the system asks for help instead of looping.
• The behaviours’ frames and costmap topics are configured.

6. Architecture

failure ─▶ context recovery (clear costmap) ─▶ RoundRobin: clear both ─▶ spin ─▶ wait ─▶ back up ─▶ (retry planning) … after 6 retries: fail and report

7. Implementation

1. Read the behaviour tree used by your configuration.
2. Remove or replace recoveries that are unsafe for your robot.
3. Set distances and speeds to the space and the robot.
4. Simulate failures and check the escalation order (below).
5. Test each recovery physically in a safe place.

actions = ["clear costmaps", "spin 1.57 rad", "wait 5 s", "back up 0.30 m"]   # RoundRobin order in the default behaviour tree
def run(failures, retries=6):
    log, rr = [], 0
    for n in range(1, failures + 1):
        if n > retries:
            log.append(f"failure {n}: retries exhausted -> navigation fails")
            break
        log.append(f"failure {n}: {actions[rr % len(actions)]}")
        rr += 1
    return log
print("\n".join(run(8)))

Printed (checked by the site’s tests):

failure 1: clear costmaps
failure 2: spin 1.57 rad
failure 3: wait 5 s
failure 4: back up 0.30 m
failure 5: clear costmaps
failure 6: spin 1.57 rad
failure 7: retries exhausted -> navigation fails

Reading it: repeated failures run the recoveries in turn (clear costmaps, spin, wait, back up, then again clear costmaps and spin), and the seventh failure exhausts the six retries so navigation fails. This is a simplified model of the tree’s round-robin: the real tree also runs a context recovery first and resets on a goal update.

8. Real examples

• Robot with no rear sensor: remove the backup recovery or add a rear sensor that the backup behaviour checks.

9. Failure scenarios

• A spin recovery in a corridor narrower than the robot’s swept circle.
• Backing up blind.
• An endless loop of recoveries with no call for help.

10. Troubleshooting

1. Log which recovery ran and what the failure code was.
2. If recoveries repeat without changing anything, change the planner or inflation instead.
3. Check that the costmap clearing services are available.

11. Validation

• The simulation prints the lines shown (executed by the site tests).
• Each recovery has been tested on the robot in a safe place.

12. Engineering checklist

• Recoveries chosen for the robot
• Unsafe ones removed
• Distances and speeds set
• Order checked
• Help request after the last retry
• Tested physically

13. Further references

• Default behaviour tree: navigate_to_pose_w_replanning_and_recovery.xml, read 2026-11-06.
• Nav2 default parameters (jazzy branch): nav2_bringup/params/nav2_params.yaml, read 2026-11-06.

Related on FixTheRobot