This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 004f790500a fix(api): disable uvloop if PYTHONASYNCIODEBUG=1 to
prevent segfault … (#61281)
004f790500a is described below
commit 004f790500a879b6b1fc44164be8a51ab25efbfe
Author: subhash-0000 <[email protected]>
AuthorDate: Sun Feb 15 05:52:27 2026 +0530
fix(api): disable uvloop if PYTHONASYNCIODEBUG=1 to prevent segfault …
(#61281)
* 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
---------
Co-authored-by: Jason(Zhe-You) Liu
<[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 bc344decb9d..146ee6952c2 100644
--- a/airflow-core/docs/administration-and-deployment/web-stack.rst
+++ b/airflow-core/docs/administration-and-deployment/web-stack.rst
@@ -58,6 +58,26 @@ separately. This might be useful for scaling them
independently or for deploying
# 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>`_.
+
Server Types
------------
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
