Как исправить падение Flask в режиме отладки на macOS

Почему flask run --debug на macOS падает с OSError: Too many open files. Разбор причины и решение — пересоздать venv и переустановить Flask. Стабильная отладка.

Когда минимальное приложение Flask нормально запускается с flask run, но ломается при flask run --debug, это может сбивать с толку. На macOS 15.5 с Python 3.12.7 и Flask 3.0.3 запуск в режиме отладки вывел предупреждение наблюдателя файловой системы, а после загрузки страницы всё упало с OSError: Too many open files. Источником проблемы оказалась виртуальная среда Python.

Воспроизведение в нескольких строках

Само приложение может быть столь же простым, как один маршрут. Обычный запуск проходит успешно; запуск с флагом отладки приводит к ошибке, описанной ниже.

from flask import Flask

webapp = Flask(__name__)

@webapp.get("/")
def greet():
    return "Hello, world"

# Сохраните как server.py и запустите через Flask CLI

При запуске в режиме отладки появляется предупреждение о fsevents и происходит откат к kqueue, после чего при попытке загрузить страницу возникает внутренняя ошибка сервера с сообщением о слишком большом числе открытых файлов.

/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

Что происходит

Поведение связано именно с режимом отладки. В нём стек пытается импортировать fsevents для отслеживания изменений в файловой системе и сообщает, что откатывается к kqueue. После этого загрузка страницы приводит к OSError: Too many open files. Добавление MacFSEvents в requirements.txt ничего не меняет. Логичная рабочая гипотеза: проблема в самой среде.

Решение, которое сработало

Полное пересоздание виртуальной среды всё исправило. Удаление существующего venv, создание нового и установка только Flask вернули режим отладки к нормальной работе. Менять код не потребовалось.

# из корня проекта
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install Flask

# Укажите приложение и запустите в режиме отладки
export FLASK_APP=server.py
flask run --debug

Почему это важно

Запуск в обычном и отладочном режимах — не одно и то же. При старте в отладке включаются дополнительные механизмы выполнения, и проблемы битой или неправильно настроенной среды могут проявляться только в этом режиме. Если команды, похожие на продакшн, выглядят исправно, а отладка сразу падает с системными ошибками, сброс среды — часто самый надёжный способ убрать скрытые поломки.

Вывод

Если flask run работает, а flask run --debug показывает предупреждение о переходе с fsevents на kqueue и затем падает с OSError: Too many open files, пересоздайте виртуальную среду и установите только Flask. Этого простого сброса оказалось достаточно, чтобы вернуть отладку и стабилизировать локальную разработку.