ROS 2 node shutdown

ROS 2 node shutdown: Ctrl+C, SIGTERM, “rcl_shutdown already called” and launch’s 5-second escalation (measured on Humble, Jazzy, Lyrical)

Short answer: in a ROS 2 Python node, catch KeyboardInterrupt (Ctrl+C) and ExternalShutdownException (kill/SIGTERM) around rclpy.spin(), do your cleanup in finally, and end with rclpy.try_shutdown() instead of rclpy.shutdown(). On Humble and Jazzy the plain rclpy.shutdown() raised rcl_shutdown already called after every Ctrl+C or SIGTERM in my tests. On Lyrical, SIGTERM doesn’t produce ExternalShutdownException at all, so the exit code changes. If your node runs under ros2 launch and cleanup takes more than 5 seconds, raise sigterm_timeout, or launch kills the node about 10 seconds after Ctrl+C.

ros2 launch: "failed to terminate '5' seconds after receiving 'SIGINT'" — measured results table
At a glance: the main measured table from this article. Full details below.

What I ran

On 2026-10-27 I ran one small node in the official ros:humble-ros-base, ros:jazzy-ros-base and ros:lyrical-ros-base Docker images. The node spins a 10 Hz timer. After 2–3 seconds the test script sends it SIGINT (what Ctrl+C sends) or SIGTERM (what kill, docker stop and launch’s escalation send). The node logs which exception reached it, whether finally ran, and what the shutdown call did. The SIGTERM case was repeated 5 times with the timer and 5 times without it on each distro. Every repeat gave the same result.

Shutdown behavior by distro: SIGINT gives KeyboardInterrupt everywhere; SIGTERM gives ExternalShutdownException on Humble and Jazzy but RCLError on Lyrical; rclpy.shutdown after Ctrl+C raises already called on Humble and Jazzy; try_shutdown is fine everywhere; with rclpy.init works only on Lyrical
One row per thing that can go wrong at shutdown.

The pattern that worked on all three

import rclpy
from rclpy.executors import ExternalShutdownException
from rclpy.node import Node

def main():
    rclpy.init()
    node = Node("my_node")
    try:
        rclpy.spin(node)
    except (KeyboardInterrupt, ExternalShutdownException):
        pass
    finally:
        # save files, stop motors, etc.
        node.destroy_node()
        rclpy.try_shutdown()

On Humble and Jazzy this handled both signals and exited with code 0. On Lyrical it handled Ctrl+C the same way, but SIGTERM raised an exception the except line doesn’t catch. More on that below.

If the node loops on rate.sleep() instead of rclpy.spin(), shutdown arrives as ROSInterruptException. That case is measured in ROSInterruptException from rate.sleep() after rclpy.shutdown().

“rcl_shutdown already called”

Swap rclpy.try_shutdown() for rclpy.shutdown() in the code above, and Humble and Jazzy print this after every Ctrl+C and every SIGTERM:

RCLError: failed to shutdown: rcl_shutdown already called on the given context

rclpy’s signal handler has already shut the context down by the time your finally runs. try_shutdown() skips the call when that’s the case. On Lyrical, plain rclpy.shutdown() after Ctrl+C returned without an error, but try_shutdown() works there too, so it’s the one to use if your code has to run on several distros.

SIGTERM on Lyrical: RCLError instead of ExternalShutdownException

On Humble (rclpy 3.3.22) and Jazzy (7.1.12), SIGTERM made rclpy.spin() raise ExternalShutdownException 10 times out of 10. On Lyrical (rclpy 10.0.11) it raised this 10 times out of 10:

rclpy._rclpy_pybind11.RCLError: failed to initialize wait set: the given context is not valid, either rcl_init() was not called or rcl_shutdown() was called., at ./src/rcl/wait.c:110

That exception isn’t one of the two in the except line, so it goes past it. In my test the finally block was still reached (it logged a line), and then the exception propagated: the process ended with a traceback and exit code 1. That matters if a supervisor such as systemd or a container restart policy treats a non-zero exit as a crash. Ctrl+C on Lyrical behaved like on the other distros. A related report is open as ros2/rclpy#1731. It describes the same RCLError-instead-of-ExternalShutdownException behavior when shutdown happens between spin_once calls. A fix is proposed in ros2/rclpy#1732 (targets rolling, still open on 2026-10-29). Its author reported that with the fix the same Lyrical setup raised ExternalShutdownException in 10 of 10 runs.

with rclpy.init(): works on Lyrical only

Newer examples use rclpy.init() as a context manager, without destroy_node() or shutdown(). On Lyrical that worked, and Ctrl+C left the with block cleanly. On Humble it failed immediately with AttributeError: __enter__, and on Jazzy with TypeError: 'NoneType' object does not support the context manager protocol. If you copy an example from the rolling branch into a Humble or Jazzy package, use the try/finally form above instead.

ros2 launch: “failed to terminate ‘5’ seconds after receiving ‘SIGINT'”

When you press Ctrl+C on ros2 launch, it sends SIGINT to each process. If a process hasn’t exited 5 seconds later, launch sends SIGTERM, and later SIGKILL. I launched the node with a cleanup step in finally that takes a fixed time, then pressed Ctrl+C. All three distros behaved the same:

Cleanup time Launch setting What happened
8 s default failed to terminate '5' seconds after receiving 'SIGINT', escalating to 'SIGTERM', but cleanup still finished (rclpy handles the SIGTERM, and the node was already in finally). Launch exited about 8 s after Ctrl+C.
14 s default Same SIGTERM message, then escalating to 'SIGKILL'. The node died with exit code -9 about 10 s after Ctrl+C, and cleanup never finished.
14 s ros2 launch my.launch.py sigterm_timeout:=20 No escalation. Cleanup finished, and launch exited about 14 s after Ctrl+C.
14 s ExecuteProcess(..., sigterm_timeout='15', sigkill_timeout='15') No escalation. Cleanup finished, and launch exited about 14 s after Ctrl+C.

So you don’t need to edit launch’s source to change the timeout. Pass sigterm_timeout:= on the command line for everything in the launch, or set it on the one action that needs it. I tested the keyword on ExecuteProcess. launch_ros‘s Node action is built on ExecuteProcess, but I didn’t test the keyword there.

A killed node that stays in ros2 node list

After kill -9 on the node, ros2 node list --no-daemon no longer showed it straight away. Plain ros2 node list, which asks the ROS 2 daemon, kept showing /sd_node for 18–20 seconds on all three distros. ros2 daemon stop cleared it immediately. So a stale entry from the daemon went away by itself within about 20 seconds here. A node that is still listed after a reboot is more likely still running somewhere, for example on another machine or in a container on the same network, but I didn’t test that case.

FAQ

How do I shut down a ROS 2 Python node cleanly?

Catch KeyboardInterrupt and ExternalShutdownException around rclpy.spin(), do cleanup in finally, and end with rclpy.try_shutdown(). On Humble and Jazzy this handled Ctrl+C and SIGTERM and exited with code 0.

Why do I get “rcl_shutdown already called on the given context”?

rclpy’s signal handler has already shut the context down by the time your finally runs. On Humble and Jazzy plain rclpy.shutdown() raised this after every Ctrl+C or SIGTERM, and try_shutdown() skips the call.

Why does SIGTERM raise RCLError instead of ExternalShutdownException on Lyrical?

On Lyrical (rclpy 10.0.11) SIGTERM raised RCLError: failed to initialize wait set 10 times out of 10. The finally block was still reached, but the process ended with a traceback and exit code 1. A related report is open as ros2/rclpy#1731.

How do I fix “failed to terminate ‘5’ seconds after receiving ‘SIGINT'” in ros2 launch?

Pass sigterm_timeout:=20 on the ros2 launch command line, or set sigterm_timeout on the ExecuteProcess action. With the default, a 14 s cleanup was killed with exit code -9 about 10 s after Ctrl+C.

Why does a killed node stay in ros2 node list?

Plain ros2 node list asks the ROS 2 daemon, which kept showing the node for 18–20 seconds after kill -9. ros2 node list --no-daemon no longer showed it straight away, and ros2 daemon stop cleared it immediately.

Not tested

C++ nodes (rclcpp::on_shutdown), MultiThreadedExecutor, lifecycle nodes, launch_ros Node(...) with the timeout keywords, Kilted and Rolling. All runs used Docker as root on Linux.

Scripts and raw output: evidence folder. Questions this answers: Actual good way to close nodes, Setting the SIGINT and SIGTERM timeout in ROS2, ros2 humble to kill the “zombie” node. Related: rclpy Rate.sleep() blocking forever.