Kyle McChesney
08/03/2026, 9:54 PMPrefectFutureList from a flow (called as a local subflow) result in the list being resolved into the mapped task results? Is there docs about this?Marvin
08/03/2026, 9:54 PMMarvin
08/03/2026, 9:56 PMPrefectFutureList, Prefect resolves the contained futures when the flow finishes, and the caller receives their states, not the task result values themselves.
So for a local subflow call:
python
@flow
def child():
return my_task.map([1, 2, 3])
@flow
def parent():
x = child()
print(type(x))
return x
the returned value is effectively:
- resolved from PrefectFutureList[PrefectFuture]
- into a plain list[State]
not list[result]
In other words: the futures are resolved, but to State objects, not to the mapped task outputs.
There is code in Prefect 3.x that explicitly does this:
- flow completion calls resolve_futures_to_states(...)
- and if the result is a PrefectFutureList, it is downcast to a normal list so you don’t end up with a PrefectFutureList containing non-futures
There’s also a test covering this behavior.
Docs
The most relevant docs I found are in the flows concepts page:
- Flows concept docs
Relevant points there:
- nested/local subflows resolve passed task futures into data
- when a flow returns futures/states, Prefect determines the final state by resolving futures to states
That docs page hints at the behavior, but it does not seem to clearly spell out the exact PrefectFutureList -> list[State] return-type behavior. For that, the source/tests are more definitive.
Practical takeaway
If you want actual mapped values from the subflow, resolve them inside the subflow before returning, e.g. return concrete data instead of the future list.
Example:
python
@task
def add_one(x):
return x + 1
@flow
def child():
futures = add_one.map([1, 2, 3])
return [f.result() for f in futures]
@flow
def parent():
return child()
Then parent() gets [2, 3, 4], not a list of states.
If you want, I can also show a tiny reproducible example demonstrating the exact returned types for:
- top-level flow
- local subflow
- return_state=True cases