python/cpython · error · TypeError

A future is required for source argument

Error message

A future is required for source argument

What it means

_chain_future() (used by asyncio.wrap_future, Future chaining, run_coroutine_threadsafe internals) validates that source is an asyncio Future or a concurrent.futures.Future. Passing a coroutine, Task is fine (Task is a Future), but a raw coroutine, None, or another awaitable raises this TypeError.

Source

Thrown at Lib/asyncio/futures.py:381

    done, cancelled, result, exception = source._get_snapshot()
    assert done
    if cancelled:
        dest.cancel()
    elif exception is not None:
        dest.set_exception(_convert_future_exc(exception))
    else:
        dest.set_result(result)

def _chain_future(source, destination):
    """Chain two futures so that when one completes, so does the other.

    The result (or exception) of source will be copied to destination.
    If destination is cancelled, source gets cancelled too.
    Compatible with both asyncio.Future and concurrent.futures.Future.
    """
    if not isfuture(source) and not isinstance(source,
                                               concurrent.futures.Future):
        raise TypeError('A future is required for source argument')
    if not isfuture(destination) and not isinstance(destination,
                                                    concurrent.futures.Future):
        raise TypeError('A future is required for destination argument')
    source_loop = _get_loop(source) if isfuture(source) else None
    dest_loop = _get_loop(destination) if isfuture(destination) else None

    def _set_state(future, other):
        if isfuture(future):
            _copy_future_state(other, future)
        else:
            _set_concurrent_future_state(future, other)

    def _call_check_cancel(destination):
        if destination.cancelled():
            if source_loop is None or source_loop is events._get_running_loop():
                source.cancel()
            else:
                source_loop.call_soon_threadsafe(source.cancel)

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Wrap coroutines first: asyncio.ensure_future(coro) or loop.create_task(coro)
2. For concurrent.futures futures, use asyncio.wrap_future(cf_future)
3. If implementing the chaining yourself, check asyncio.isfuture(x) before calling

Example fix

# before
asyncio.wrap_future(my_coroutine)  # TypeError: source argument

# after
task = asyncio.ensure_future(my_coroutine)
asyncio.wrap_future(task)  # Task IS a Future

import asyncio, concurrent.futures
ok = asyncio.isfuture(src) or isinstance(src, concurrent.futures.Future)

def is_chainable_source(obj) -> bool:
    import asyncio, concurrent.futures
    return asyncio.isfuture(obj) or isinstance(obj, concurrent.futures.Future)

When it happens

Trigger: asyncio.wrap_future(coro) with a coroutine instead of a future; future.add_done_callback chains hand-rolled; calling private _chain_future with a Promise-like object (e.g. a trio future).

Common situations: Confusing wrap_future (concurrent -> asyncio bridging) with ensure_future (scheduling); passing the result of an async function instead of a Task; third-party awaitables that duck-type but do not subclass Future.

Related errors

• A future is required for destination argument
• {future!r} object does not appear to be compatible with asyn
• Not implemented
• Unknown thread safety level {level!r} for {name!r}. Valid le
• Socket cannot be of type SSLSocket

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/fbeb7a53c8f4dd53. Report an issue: GitHub.