What are you really trying to do?
I am upgrading a production service to use the latest Python environments (specifically testing against Python 3.14 alpha/dev builds). I encountered a regression where Temporal workflows fail immediately when scheduling activities due to changes in how Python 3.14 handles asyncio.Task initialization and closure cell inspection. I am reporting this so the SDK can be made compatible with the upcoming Python 3.14 release.
Describe the bug
In Python 3.14, any workflow calling await workflow.execute_activity(...) fails with a NameError.
This is caused by a "binding lag" in _workflow_instance.py. The variable handle is annotated but not assigned a value before it is referenced inside the run_activity closure. While previous Python versions (up to 3.13) deferred the inspection of these cells until the coroutine actually executed, Python 3.14’s asyncio.Task constructor (specifically when set_name is called) eagerly inspects the cells. Because the task is created in the same expression that binds the name, the inspection happens while the cell is still empty, triggering the error.
Traceback:
File ".../temporalio/worker/_workflow_instance.py", line 1921, in _outbound_schedule_activity
handle = _ActivityHandle(self, input, run_activity())
File ".../temporalio/worker/_workflow_instance.py", line 3047, in _ActivityHandle.__init__
instance._register_task(self, name=f"activity: {input.activity}")
File ".../temporalio/worker/_workflow_instance.py", line 2458, in _register_task
task.set_name(name)
NameError: cannot access free variable 'handle' where it is not associated with a value in enclosing scope
Minimal Reproduction
- Use a Python 3.14 environment (e.g.,
cgr.dev/chainguard/python:latest-dev).
- Run any standard "Hello World" workflow.
- Attempt to execute an activity.
- The worker will catch a
NameError during the _outbound_schedule_activity call.
The problematic code pattern in _workflow_instance.py:
handle: _ActivityHandle # Created but UNBOUND
async def run_activity() -> Any:
while True:
handle._started = True # Closure reference
...
# Python 3.14 fails here because run_activity()
# is inspected during Task creation inside the _ActivityHandle init
handle = _ActivityHandle(self, input, run_activity())
Environment/Versions
- OS and processor: Linux (verified on x86_64/Aarch64 via Chainguard images)
- Temporal Version: SDK versions 1.21.1 through 1.26.0 (current stable range)
- Python Version: 3.14.0a (early 2026 dev builds)
- Deployment: Docker-based workers
Additional context
A temporary runtime patch confirms that pre-binding the variable resolves the issue:
handle: Optional[_ActivityHandle] = None # Explicit binding fixes the NameError
This issue will likely affect all users as they begin migrating to Python 3.14 later this year, or those using "floating" rolling-release base images in their CI/CD pipelines.
What are you really trying to do?
I am upgrading a production service to use the latest Python environments (specifically testing against Python 3.14 alpha/dev builds). I encountered a regression where Temporal workflows fail immediately when scheduling activities due to changes in how Python 3.14 handles
asyncio.Taskinitialization and closure cell inspection. I am reporting this so the SDK can be made compatible with the upcoming Python 3.14 release.Describe the bug
In Python 3.14, any workflow calling
await workflow.execute_activity(...)fails with aNameError.This is caused by a "binding lag" in
_workflow_instance.py. The variablehandleis annotated but not assigned a value before it is referenced inside therun_activityclosure. While previous Python versions (up to 3.13) deferred the inspection of these cells until the coroutine actually executed, Python 3.14’sasyncio.Taskconstructor (specifically whenset_nameis called) eagerly inspects the cells. Because the task is created in the same expression that binds the name, the inspection happens while the cell is still empty, triggering the error.Traceback:
Minimal Reproduction
cgr.dev/chainguard/python:latest-dev).NameErrorduring the_outbound_schedule_activitycall.The problematic code pattern in
_workflow_instance.py:Environment/Versions
Additional context
A temporary runtime patch confirms that pre-binding the variable resolves the issue:
This issue will likely affect all users as they begin migrating to Python 3.14 later this year, or those using "floating" rolling-release base images in their CI/CD pipelines.