Fix WebSocketError: RuntimeError: You need to use a gevent or eventlet server for WebSocket support in Flask

This error occurs when Flask-SocketIO is used with a WSGI server that does not support WebSockets. The default Flask development server and Gunicorn without async workers cannot handle WebSocket connections. Fix it by running your app with eventlet or gevent, or by configuring Gunicorn with the eventlet worker class.

Reading the Stack Trace

Here's what each line means:

• File "/app/venv/lib/python3.12/site-packages/flask_socketio/__init__.py", line 210, in run: Flask-SocketIO's run method initializes the server but detects that neither eventlet nor gevent is installed.
• File "/app/venv/lib/python3.12/site-packages/flask_socketio/__init__.py", line 142, in _init_app: During app initialization, Flask-SocketIO checks for an async-capable server and raises if none is found.
• RuntimeError: You need to use a gevent or eventlet server for WebSocket support.: The error confirms that the current runtime does not support WebSocket connections.

Common Causes

# requirements.txt
Flask==3.0.0
Flask-SocketIO==5.3.6
# missing: eventlet or gevent

# Procfile
web: gunicorn app:app  # default sync worker, no WebSocket support

# Terminal:
$ flask run  # does not start the SocketIO server

The Fix

Install eventlet and configure Gunicorn to use the eventlet worker class. This gives the server async capabilities needed for WebSocket connections. Use a single worker (-w 1) with eventlet since it handles concurrency via green threads.

# Procfile
web: gunicorn app:app

# requirements.txt (add eventlet)
eventlet==0.35.2

# Procfile
web: gunicorn --worker-class eventlet -w 1 app:app

# Or for development:
# socketio.run(app, debug=True)

Testing the Fix

import pytest
from app import create_app, socketio

@pytest.fixture
def client():
    app = create_app()
    app.config['TESTING'] = True
    return socketio.test_client(app)

def test_websocket_connects(client):
    assert client.is_connected()

def test_websocket_receives_event(client):
    client.emit('ping')
    received = client.get_received()
    assert len(received) > 0
    assert received[0]['name'] == 'pong'

def test_websocket_disconnects_cleanly(client):
    client.disconnect()
    assert not client.is_connected()

Run your tests:

pytest tests/ -v

Pushing Through CI/CD

git checkout -b fix/flask-websocket-eventlet,git add requirements.txt Procfile,git commit -m "fix: add eventlet worker for WebSocket support",git push origin fix/flask-websocket-eventlet

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest tests/ -v --tb=short
      - run: flake8 app/

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

pip install bugstack

import bugstack

bugstack.init(api_key=os.environ["BUGSTACK_API_KEY"])

Deploying the Fix (Manual Path)

1. Run pytest locally to verify WebSocket connections work with eventlet.
2. Open a pull request with the requirements and Procfile changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify WebSocket connections work in staging.

Frequently Asked Questions