This is an automated email from the ASF dual-hosted git repository.
bugraoz pushed a commit to branch v3-1-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-1-test by this push:
new 418bfb204ad [v3-1-test] fix(api): disable uvloop if
PYTHONASYNCIODEBUG=1 to prevent segfault … (#61281) (#61933)
418bfb204ad is described below
commit 418bfb204ad6bf747fbf6a8d451099961f6e6fd4
Author: Jason(Zhe-You) Liu <[email protected]>
AuthorDate: Sun Feb 15 19:05:22 2026 +0800
[v3-1-test] fix(api): disable uvloop if PYTHONASYNCIODEBUG=1 to prevent
segfault … (#61281) (#61933)
* fix(api): disable uvloop if PYTHONASYNCIODEBUG=1 to prevent segfault
(issue #61214)
* docs(newsfragment): add newsfragment for uvloop/asyncio debug segfault
fix (#61214)
* fix(api): add stacklevel for debug warning and fix rst literals
* fix: remove else block and correct newsfragment per review feedback
* docs: document PYTHONASYNCIODEBUG/PYTHONDEVMODE incompatibility (Python
3.12+)
* docs: fix RST formatting and spellcheck errors
- Add blank line after warning directive to fix RST error
- Quote asyncio with backticks to fix spellcheck
* refactor: simplify to warning-only approach per reviewer feedback
* refactor: apply reviewer suggestions
---------
(cherry picked from commit 004f790500a879b6b1fc44164be8a51ab25efbfe)
Co-authored-by: subhash-0000
<[email protected]>
---
.../docs/administration-and-deployment/web-stack.rst | 20 ++++++++++++++++++++
airflow-core/src/airflow/api_fastapi/main.py | 15 +++++++++++++++
2 files changed, 35 insertions(+)
diff --git a/airflow-core/docs/administration-and-deployment/web-stack.rst
b/airflow-core/docs/administration-and-deployment/web-stack.rst
index 5f2159649b3..45e7a0396ea 100644
--- a/airflow-core/docs/administration-and-deployment/web-stack.rst
+++ b/airflow-core/docs/administration-and-deployment/web-stack.rst
@@ -57,3 +57,23 @@ separately. This might be useful for scaling them
independently or for deploying
airflow api-server --apps core
# serve only the Execution API Server
airflow api-server --apps execution
+
+Known Issues
+------------
+
+Incompatibility with ``PYTHONASYNCIODEBUG`` and ``PYTHONDEVMODE``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+ The API server may crash with a segmentation fault when the environment
variable
+ ``PYTHONASYNCIODEBUG=1`` is set or when running in ``PYTHONDEVMODE`` on
Python 3.12 or later.
+ This is due to an incompatibility between ``uvloop`` (used by Uvicorn for
improved performance)
+ and Python's ``asyncio`` debug mode.
+
+ If you need to debug ``asyncio`` issues in the API server, consider:
+
+ * Debugging at the application level rather than relying on
``PYTHONASYNCIODEBUG`` or ``PYTHONDEVMODE``
+ * Setting up a development environment without uvloop installed
+
+ This is a known limitation tracked in `issue #61214
<https://github.com/apache/airflow/issues/61214>`_.
diff --git a/airflow-core/src/airflow/api_fastapi/main.py
b/airflow-core/src/airflow/api_fastapi/main.py
index 195f98a5bf3..c71b4d9b0d4 100644
--- a/airflow-core/src/airflow/api_fastapi/main.py
+++ b/airflow-core/src/airflow/api_fastapi/main.py
@@ -18,11 +18,26 @@
from __future__ import annotations
import os
+import sys
# Mark this as a server context before any airflow imports
# This ensures plugins loaded at import time get the correct secrets backend
chain
os.environ["_AIRFLOW_PROCESS_CONTEXT"] = "server"
+# Warn if PYTHONASYNCIODEBUG or PYTHONDEVMODE is set on Python 3.12+ (see
Airflow issue #61214)
+if sys.version_info >= (3, 12) and (
+ os.environ.get("PYTHONASYNCIODEBUG") == "1" or
os.environ.get("PYTHONDEVMODE") == "1"
+):
+ import warnings
+
+ warnings.warn(
+ "PYTHONASYNCIODEBUG or PYTHONDEVMODE detected on Python 3.12+: "
+ "The API server may crash due to uvloop incompatibility with asyncio
debug mode. "
+ "See https://github.com/apache/airflow/issues/61214 for details.",
+ RuntimeWarning,
+ stacklevel=2,
+ )
+
from airflow.api_fastapi.app import cached_app
# There is no way to pass the apps to this file from Airflow CLI
