[Triage] gthread worker deadlocks on fork due to control socket thread (Python 3.12)

[cabilash0]

Type

Bug Report

Description

After upgrading to gunicorn 25.1.0, gthread workers intermittently deadlock during fork() on Python 3.12. The master process starts successfully and listens on the configured port, but the forked worker hangs permanently during initialization, the "Booting worker with pid" message never appears. This causes the application to become completely unresponsive (nginx returns 499/504)

The issue is triggered by the new control socket feature introduced in 25.1.0 (I think?). The control socket listener thread running in the master process holds a lock at the moment of fork(), and the forked child inherits that lock in a permanently locked state, resulting in a futex deadlock.

Steps to Reproduce (for bugs)

#!/bin/bash
# Reproduction script for gunicorn 25.1.0 control socket fork deadlock on Python 3.12
# Run on a vanilla AL2023 instance
# Usage: ./gunicorn_deadlock_repro.sh [gunicorn_version]
# Examples:
#   ./gunicorn_deadlock_repro.sh          # tests 25.1.0 (default)
#   ./gunicorn_deadlock_repro.sh 25.0.3   # tests 25.0.3

GUNICORN_VERSION="${1:-25.1.0}"

set -e

Setup
sudo dnf install -y python3.12 python3.12-pip
rm -rf /tmp/gunicorn-test
mkdir -p /tmp/gunicorn-test && cd /tmp/gunicorn-test
python3.12 -m venv venv
source venv/bin/activate
# Create minimal WSGI app
cat > application.py << 'APPEOF'
def application(environ, start_response):
    response = b"ok"
    start_response("200 OK", [("Content-Type", "text/plain"), ("Content-Length", str(len(response)))])
    return [response]
APPEOF
pip install "gunicorn==$GUNICORN_VERSION"

echo "============================================"
echo "Testing gunicorn $GUNICORN_VERSION on Python 3.12"
echo "============================================"


# Initial boot
gunicorn --bind 127.0.0.1:8000 --workers=1 --threads=15 application &
MASTER_PID=$!
sleep 2

if curl -s --max-time 3 http://127.0.0.1:8000/ > /dev/null 2>&1; then
    echo "Initial boot: OK"
else
    echo "Initial boot failed, exiting"
    exit 1
fi

# Restart loop to trigger deadlock
for i in $(seq 1 20); do
    kill -TERM $MASTER_PID 2>/dev/null
    sleep 1
    gunicorn --bind 127.0.0.1:8000 --workers=1 --threads=15 application &
    MASTER_PID=$!
    sleep 3
    if ! curl -s --max-time 3 http://127.0.0.1:8000/ > /dev/null 2>&1; then
        WORKER_PID=$(ps --ppid $MASTER_PID -o pid= | head -1 | tr -d ' ')
        echo "DEADLOCK on iteration $i (worker pid: $WORKER_PID)"
        echo "Worker kernel stack:"
        sudo cat /proc/$WORKER_PID/stack
        echo "Worker wchan:"
        sudo cat /proc/$WORKER_PID/wchan
        echo ""
        echo "Cleaning up..."
        kill -TERM $MASTER_PID 2>/dev/null
        exit 1
    fi
    echo "Iteration $i: OK"
done

echo "No deadlock in 20 iterations with gunicorn $GUNICORN_VERSION."
kill -TERM $MASTER_PID 2>/dev/null

Configuration

gunicorn --bind 127.0.0.1:8000 --workers=1 --threads=15 application

Logs / Error Output

No response

Gunicorn Version

gunicorn (version 25.1.0)

Python Version

Python 3.12.12 (main, Feb 5 2026, 00:00:00) [GCC 11.5.0 20240719 (Red Hat 11.5.0-5)] on linux

Worker Class

gthread

Operating System

AL2023

Additional Context

No response

Checklist

• I have searched existing discussions and issues for duplicates
• I have checked the documentation and FAQ

[cabilash0]

Opened erronesouly