puma start causes "There is already a server bound to: <socket>" error

Question

I haven't been able to reliably reproduce this issue, so I'll describe what's happening and hope one of you wise puma kids out there can help me out.

I always stop and start puma at the end of my deploy process. I run pumactl -F <config_path> stop, which works, and then the command puma -q -d -e staging -C <config_path>, which sometimes (not always) causes the following error:

[12802] Puma starting in cluster mode... 
[12802] * Version 2.11.3 (ruby 2.1.2-p95), codename: Intrepid Squirrel
[12802] * Min threads: 2, max threads: 4
[12802] * Environment: staging
[12802] * Process workers: 2
[12802] * Phased restart available 
[12802] * Listening on unix:///<app_dir>/tmp/puma/sockets/puma.sock 
<ruby_path>/2.1.0/gems/puma-2.11.3/lib/puma/binder.rb:284:in `add_unix_listener': There is already a server bound to: <app_dir>/tmp/puma/sockets/puma.sock (RuntimeError)
<ruby_path>/2.1.0/gems/puma-2.11.3/lib/puma/binder.rb:124:in `block in parse'
<ruby_path>/2.1.0/gems/puma-2.11.3/lib/puma/binder.rb:82:in `each'
<ruby_path>/2.1.0/gems/puma-2.11.3/lib/puma/binder.rb:82:in `parse'
<ruby_path>/2.1.0/gems/puma-2.11.3/lib/puma/cluster.rb:325:in `run'
<ruby_path>/2.1.0/gems/puma-2.11.3/lib/puma/cli.rb:216:in `run'
<ruby_path>/2.1.0/gems/puma-2.11.3/bin/puma:10:in `<top (required)>'
<ruby_path>/2.1.0/bin/puma:23:in `load'
<ruby_path>/2.1.0/bin/puma:23:in `<main>'

If I try to run the same puma start command again afterwards, it works.

Here's my puma config:

#!/usr/bin/env puma

directory "<app_dir>/current"
rackup "<app_dir>/current/config.ru"
environment "staging"

pidfile "<app_dir>/tmp/puma/pid"
state_path "<app_dir>/tmp/puma/state"
activate_control_app "<app_dir>/tmp/puma/sockets/pumactl.sock"

stdout_redirect "<app_dir>/shared/log/puma.error.log", "<app_dir>/shared/log/puma.access.log", true

threads 2,4

bind "unix:///<app_dir>/tmp/puma/sockets/puma.sock"

workers 2

My questions:

1. How can I reproduce this error?
2. How can I fix it? Is this a problem with puma or with my configuration?

Answer 1

Instead of running both commands...

pumactl -F <config_path> stop
puma -q -d -e <env> -C <config_path>

just use the restart command:

pumactl -F <config_path> restart

---

Explanation

The puma README has a section on Restarting that contains no mention of calling the stop and start commands one after the other. Because that use case is unsupported, using the established method to restart the puma server will most likely clear up this issue.

Note

I was unable to consistently reproduce this puma error, so I can't 100% confirm that using pumactl restart fixes the problem. (Even though puma's lack of support for pumactl stop followed by puma implies that it does.) If someone continues to have this issue while using the supported pumactl restart, please let me know so I can modify this answer.