Issue
Gunicorn is failing to boot workers or process is not detected on deploy to Heroku
Resolution
Gunicorn can be tricky to configure at times, but the following debug steps can help narrow down a possible Gunicorn deploy issue on Heroku.
Debugging deploy issues with Gunicorn
-
Confirm it runs locally
Make sure Gunicorn is installed in your local environment and then run your exact Procfile web command from your project's home directory. If it doesn't boot up a worker successfully, it's an issue with your application, not with your deployment. -
Confirm
Gunicorn
is installed
Gunicorn needs to be in yourpipfile
orrequirements.txt
to install on Heroku. If you're using an older version, try bumping to latest to see if that helps your issue. -
Back to basics
It happens to the best of us. Check that your changes are checked into git on the correct branch, thatProcfile
is capitalized (Heroku will fail to detect the file if it is not), and that you have no spelling errors. -
Git diff
If your deploy issue happened after a change to your application, it's important to look closely at any changes in your application's code between the last successful deploy and the first sign of an issue. It's likely your issue can be found in one of those changes. -
Leverage your logs
There's a good chance that others have experienced what you're experiencing. Leverage the error messages in your logs to investigate if others have found answers or shared solutions, and be sure to check the Gunicorn issue tracker if you think you're experiencing a bug. -
Check your framework's guide to Gunicorn
The configuration you need may be different depending on the Python framework you're building your application with. Check your framework's documentation on any deployment-specific configuration you may need.
When you still need help
If you're still searching for an answer after taking these steps, reach out! To help us help you faster, include the debug steps you've taken, your logs and the exact error message you're seeing.