Flask debug crash on macOS with fsevents fallback and OSError: Too many open files — solved by recreating the virtual environment

Flask app runs normally but fails in debug on macOS with an fsevents warning and OSError: Too many open files. Fix by recreating the virtual environment.

When a minimal Flask app runs fine with flask run but breaks under flask run --debug, the contrast can be confusing. On macOS 15.5 with Python 3.12.7 and Flask 3.0.3, the debug start produced a filesystem watcher warning and then collapsed with an OSError: Too many open files after loading the page. The root of the issue turned out to be the Python virtual environment.

Repro in a few lines

The application itself can be as simple as a single route. Running it normally succeeds; starting it with the debug flag triggers the failure described below.

from flask import Flask
webapp = Flask(__name__)
@webapp.get("/")
def greet():
    return "Hello, world"
# Save as server.py and run with Flask CLI

Starting in debug mode emits a warning about fsevents and falls back to kqueue, then attempting to load the page results in an internal server error with too many open files.

/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/watchdog/observers/__init__.py:68: UserWarning: Failed to import fsevents. Fall back to kqueue
warnings.warn("Failed to import fsevents. Fall back to kqueue", stacklevel=1)

OSError: [Errno 24] Too many open files

What’s going on

The behavior is tied to debug mode. In this mode, the stack attempts to import fsevents for filesystem watching and reports that it falls back to kqueue. After that, loading the page leads to OSError: Too many open files. Including MacFSEvents in requirements.txt does not change the outcome. The working hypothesis becomes straightforward: the environment itself is at fault.

Fix that worked

Recreating the virtual environment resolved everything. Removing the existing venv, creating a new one, and installing only Flask brought debug mode back to normal operation. No code changes were required.

# from the project root
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install Flask
# Set the app and run in debug
export FLASK_APP=server.py
flask run --debug

Why this matters

Debug and non-debug runs are not identical. The debug startup path activates additional runtime behavior, and a broken or misconfigured environment can surface only under that path. When production-like commands appear healthy but debug mode immediately fails with system-level errors, resetting the environment can be the most reliable way to eliminate subtle breakage.

Conclusion

If flask run is fine but flask run --debug shows a fsevents fallback warning and then crashes with OSError: Too many open files, recreate the virtual environment and install just Flask. This simple reset was sufficient to restore debug mode and stabilize local development.