#3639·puma

Puma returns exit code 1 in docker container on SIGTERM

Author: modoscCreated Mar 27, 2025Updated Jun 29, 2026

Labelsdocs

Describe the bug this was originally filed here but i figured it made more sense to open a new issue)

when puma is running in a container sending a SIGTERM gracefully shuts the server down but results in an exit code of 1, which is interpreted as an application error (see 1, 2).

instead the container should exit with 143.

this may seem trivial but it has caused problems for me multiple times when dealing with aws support - when they see the exit code they immediately assume there's an application error and i have to explain and point them to the old issue.

Puma config: no puma config required

To Reproduce

full reproduction here (i tried using the docker instructions below but they didn't work for me, i filed https://github.com/puma/puma/issues/3638 to track)

(UPDATE: with the changes in https://github.com/puma/puma/pull/3641 it's possible to reproduce it with the provided Dockerfile)

bash

$ bundle install
$ docker build -t puma-repro .
$ docker run -it puma-repro
$ docker run -it puma-repro
Puma starting in single mode...
* Puma version: 6.6.0 ("Return to Forever")
* Ruby version: ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [aarch64-linux]
*  Min threads: 0
*  Max threads: 5
*  Environment: development
*          PID: 1
* Listening on http://0.0.0.0:3000
Use Ctrl-C to stop

in another terminal:

bash

$ docker ps |grep puma-repro
d5e835a18867   puma-repro        "bin/puma -b tcp://0…"   39 seconds ago   Up 39 seconds                                                 jolly_leavitt
$ docker kill --signal=TERM d5e835a18867
d5e835a18867

in the first container we see puma exiting gracefully but the exit code is 1:

bash

- Gracefully stopping, waiting for requests to finish
$ echo $?
1

you can also see this in docker:

bash

work ~/git/horizon-api [main|⚑ 82]$ docker container ls -a |grep puma-repro
d5e835a18867   puma-repro                                              "bin/puma -b tcp://0…"   2 minutes ago    Exited (1) About a minute ago                                        jolly_leavitt

Expected behavior puma should exit with 143, which is the behavior when running directly in a shell:

bash

$ bin/puma -b tcp://0.0.0.0:3000 config.ru
Puma starting in single mode...
* Puma version: 6.6.0 ("Return to Forever")
* Ruby version: ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [arm64-darwin24]
*  Min threads: 0
*  Max threads: 5
*  Environment: development
*          PID: 15308
* Listening on http://0.0.0.0:3000
Use Ctrl-C to stop

in another terminal:

bash

$ kill -TERM 15308

back in the first:

bash

- Gracefully stopping, waiting for requests to finish
Terminated: 15
$ echo $?
143

Desktop (please complete the following information):

OS: mac (24.3.0 Darwin Kernel Version 24.3.0: Thu Jan 2 20:24:23 PST 2025; root:xnu-11215.81.4~3/RELEASE_ARM64_T6020 arm64) but this issue also shows in linux
Puma Version: 6.6.0

Source: puma/puma

View original on GitHub View discussion on GitHub