Robot gets stuck

1. Symptoms

• The robot stops and the log says it failed to make progress.
• It rotates or shuffles in place.
• It repeats the same recovery.

2. Possible causes

• Obstacles in the local costmap (real or stale) block all trajectories.
• A local minimum between the path and an obstacle.
• Progress checker thresholds too strict for the speed.
• Wheel slip or low torque so the robot does not move.
• Localisation drift pulls the path into walls.
• Recoveries unsafe or ineffective.

3. Measurements to collect

• Commanded versus measured velocity.
• Local costmap at the stuck position.
• Progress checker parameters (required movement and time).
• Localisation error.

4. Diagnostic commands

Commands are not executed by the site’s automated tests (they need a ROS 2 Jazzy installation or the robot).

ros2 topic echo /cmd_vel
ros2 topic echo /odom --field twist.twist
ros2 topic echo /local_costmap/costmap --once

5. Step-by-step investigation

1. Compare commanded and measured velocity: a gap means drive or slip.
2. View the local costmap for blocking obstacles.
3. Check the progress checker values against the real speed.
4. Check localisation against the map.
5. Check which recovery ran and whether it was effective.

6. Corrective actions

• Fix drive or slip issues.
• Clear stale obstacles by fixing sensor noise or the clearing parameters.
• Adjust critic weights or use another controller.
• Match the progress checker to realistic speeds.
• Improve localisation.

7. Validation after the fix

• No stuck events over the full trial set in the ODD’s conditions.

References

• See the recovery behaviours guide and the oscillation page.