# [nav2_planner] Failed to initialize costmap layer: 'obstacle_layer' - plugin not found or failed to load

- **ID:** `ros2/nav2-planner-failed-to-initialize-costmap-layer`
- **Domain:** ros2
- **Category:** module_error
- **Verification:** ai_generated
- **Fix Rate:** 84%

## Root Cause

The nav2 costmap layer plugin (e.g., obstacle_layer) is not registered in the pluginlib system, either because the package is not built, the plugin description XML is missing, or the plugin name is misspelled in the costmap configuration.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Humble | active | — | — |
| Iron | active | — | — |
| Rolling | active | — | — |

## Workarounds

1. **Verify the plugin is registered: run 'ros2 pkg list | grep nav2_costmap_2d' and check the plugin description file in the package share directory: cat $(ros2 pkg prefix nav2_costmap_2d)/share/nav2_costmap_2d/plugins.xml. Ensure the plugin name matches your config.** (90% success)
   ```
   Verify the plugin is registered: run 'ros2 pkg list | grep nav2_costmap_2d' and check the plugin description file in the package share directory: cat $(ros2 pkg prefix nav2_costmap_2d)/share/nav2_costmap_2d/plugins.xml. Ensure the plugin name matches your config.
   ```
2. **If the plugin is from a custom package, ensure the plugin description XML is correctly set up. In the package's CMakeLists.txt: pluginlib_export_plugin_description_file(nav2_costmap_2d plugins.xml). Then rebuild: colcon build --packages-select my_costmap_plugins** (85% success)
   ```
   If the plugin is from a custom package, ensure the plugin description XML is correctly set up. In the package's CMakeLists.txt: pluginlib_export_plugin_description_file(nav2_costmap_2d plugins.xml). Then rebuild: colcon build --packages-select my_costmap_plugins
   ```
3. **In the costmap configuration YAML, use the exact plugin name from the plugins.xml. For example: plugins: [obstacle_layer] and obstacle_layer: {plugin: 'nav2_costmap_2d::ObstacleLayer', ...}. Restart the planner node.** (80% success)
   ```
   In the costmap configuration YAML, use the exact plugin name from the plugins.xml. For example: plugins: [obstacle_layer] and obstacle_layer: {plugin: 'nav2_costmap_2d::ObstacleLayer', ...}. Restart the planner node.
   ```

## Dead Ends

- **** — The plugin name must match exactly what is registered in the plugin description XML. A typo or missing package will cause the same error. (90% fail)
- **** — If the plugin is from a custom package, apt-get won't help. You need to build your custom package with colcon and source the workspace. (85% fail)