Description

When running make serve on macOS, gunicorn workers repeatedly crash with SIGSEGV (segmentation fault) errors:

[2026-02-11 14:07:39 +0530] [55715] [WARNING] Worker (pid:55773) was sent SIGSEGV!
[2026-02-11 14:07:39 +0530] [55715] [INFO] Worker child exit (pid: 55773)

Workers spawn and immediately crash in a continuous loop, making the server unusable.

Environment

• OS: macOS (Darwin)
• Python: 3.12.12
• Gunicorn: 24.1.1
• Worker Class: uvicorn.workers.UvicornWorker
• Command: make serve (which runs gunicorn with --preload)

Root Cause

macOS has strict fork-safety requirements. When gunicorn uses the --preload flag (which loads the application in the master process before forking workers), any Python libraries that interact with:

• CoreFoundation framework
• Objective-C runtime
• Asyncio event loops
• SQLAlchemy connections

...will be in an invalid state in the forked worker processes, causing immediate SIGSEGV crashes.

The specific chain of events:

1. run-gunicorn.sh sets GUNICORN_PRELOAD_APP=true by default
2. gunicorn loads gunicorn.config.py which imports mcpgateway.config
3. mcpgateway.config imports SQLAlchemy and other async libraries
4. gunicorn forks worker processes
5. Workers inherit invalid/uninitialized state from the master process
6. Workers crash with SIGSEGV when trying to use SQLAlchemy/asyncio

References

• gunicorn issue #2761 - Fork can eventually cause sigsegv on macos
• Python bug #13829 - os.fork issues on macOS

Workarounds (Before Fix)

Users could work around this by:

1. Using make dev instead (runs uvicorn directly without forking)
2. Setting GUNICORN_PRELOAD_APP=false environment variable
3. Using Granian: make serve-granian

Solution

Disable --preload by default on macOS:

1. gunicorn.config.py: Set preload_app = platform.system() != "Darwin"
2. run-gunicorn.sh: Check for Darwin and set GUNICORN_PRELOAD_APP=false by default

This ensures workers import the application code AFTER forking, avoiding the fork-safety issues.