ROS 2 reference
Lifecycle nodes
A managed node can be alive and doing absolutely nothing, on purpose. When a stack refuses to come up and nothing throws an error, the answer is almost always a node that never reached Active.
Managed nodes have states
A lifecycle node (a managed node, class LifecycleNode) does not just run the moment you launch it. It moves through an explicit state machine so an orchestrator can bring a whole system up in a controlled order. A plain node is either running or not. A lifecycle node can be alive but deliberately doing nothing, waiting to be told it is allowed to work.
The state machine
There are four primary states: Unconfigured, Inactive, Active, and Finalized. Between them sit the transition states, Configuring, CleaningUp, Activating, Deactivating, ShuttingDown, and ErrorProcessing, which the node passes through while it runs your callbacks. The transitions you actually trigger are:
configure: Unconfigured → Inactive, runson_configure(). Allocate resources, read parameters, create publishers and subscriptions, but they do not transmit yet.activate: Inactive → Active, runson_activate(). Publishers and timers start actually running.deactivate: Active → Inactive, runson_deactivate(). Stop transmitting, keep the resources.cleanup: Inactive → Unconfigured, runson_cleanup(). Free everything you created in configure.shutdown: from any state → Finalized. The node is done.
Who drives the transitions
Either you, by hand, with ros2 lifecycle set, or an orchestrator. Nav2 uses a lifecycle_managerthat configures and activates its nodes in a fixed order on startup (autostart), and uses “bond” connections to detect if a managed node dies. If any node fails to reach Active, the manager stops and the stack does not come up.
The failures, and their tells
- Node is listed and alive but publishes nothing
- It is stuck in Unconfigured or Inactive. It never got activated, so its lifecycle publishers drop every message.
- on_configure never completes / node stays Unconfigured
- on_configure returned FAILURE, usually a missing or invalid parameter. Read the node log for the reason it refused to configure.
- Nav2 hangs at startup with no obvious error
- One lifecycle-managed node failed to activate, so lifecycle_manager halted. Check which node is not Active.
- Node was working, then went silent
- Something deactivated it (a bond timeout or a manual deactivate). It is back in Inactive, alive but mute.
- Transition rejected
- You requested an illegal transition for the current state (e.g. activate from Unconfigured). Configure first, then activate.
Inspecting lifecycle state
List and query
Start by finding out which nodes are managed at all, then ask each one where it currently sits and what it will let you do next.
# Which nodes are lifecycle-managed?
ros2 lifecycle nodes
# What state is this node in right now?
ros2 lifecycle get /planner_server
# What transitions are currently available?
ros2 lifecycle list /planner_serverDrive it by hand
When no orchestrator is doing it for you, walk the node up yourself. If a step fails, the node’s log carries the real reason.
# Bring a node up manually: configure, then activate
ros2 lifecycle set /planner_server configure
ros2 lifecycle set /planner_server activate
# If activate fails, the node log tells you why on_configure/on_activate refusedFix it in a lab
A stack that will not start because a node never reached Active is a lifecycle bug you diagnose in a real container, not on a slide. Open a lab and find the node that is alive but mute.