Debugging deploy issues with Gunicorn

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

  1. 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.

  2. Confirm Gunicorn is installed
    Gunicorn needs to be in your pipfile or requirements.txt to install on Heroku. If you're using an older version, try bumping to latest to see if that helps your issue.

  3. Back to basics
    It happens to the best of us. Check that your changes are checked into git on the correct branch, that Procfile is capitalized (Heroku will fail to detect the file if it is not), and that you have no spelling errors.

  4. 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.

  5. 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.

  6. 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.

Ask on Stack Overflow

Engage with a community of passionate experts to get the answers you need

Ask on Stack Overflow

Heroku Support

Create a support ticket and our support experts will get back to you

Contact Heroku Support