python/cpython · error · RuntimeError

sendfile is not supported for transport {transport!r}

Error message

sendfile is not supported for transport {transport!r}

What it means

A RuntimeError raised by loop.sendfile() when the transport does not support sendfile at all (its _sendfile_compatible attribute is UNSUPPORTED). Only specific transports (e.g. _SelectorSocketTransport on suitable platforms) advertise compatibility; SSL transports, pipes, subprocess pipes, and proxies report unsupported, and the message names the offending transport.

Source

Thrown at Lib/asyncio/base_events.py:1280

        count is the total number of bytes to transmit as opposed to
        sending the file until EOF is reached. File position is updated on
        return or also in case of error in which case file.tell()
        can be used to figure out the number of bytes
        which were sent.

        fallback set to True makes asyncio to manually read and send
        the file when the platform does not support the sendfile syscall
        (e.g. Windows or SSL socket on Unix).

        Raise SendfileNotAvailableError if the system does not support
        sendfile syscall and fallback is False.
        """
        if transport.is_closing():
            raise RuntimeError("Transport is closing")
        mode = getattr(transport, '_sendfile_compatible',
                       constants._SendfileMode.UNSUPPORTED)
        if mode is constants._SendfileMode.UNSUPPORTED:
            raise RuntimeError(
                f"sendfile is not supported for transport {transport!r}")
        if mode is constants._SendfileMode.TRY_NATIVE:
            try:
                return await self._sendfile_native(transport, file,
                                                   offset, count)
            except exceptions.SendfileNotAvailableError:
                if not fallback:
                    raise

        if not fallback:
            raise exceptions.SendfileNotAvailableError(
                f"fallback is disabled and native sendfile is not "
                f"supported for transport {transport!r}")
        return await self._sendfile_fallback(transport, file,
                                             offset, count)

    async def _sendfile_native(self, transp, file, offset, count):
        raise exceptions.SendfileNotAvailableError(

View on GitHub (pinned to bc6749cc3b)

Solutions

Use fallback=True so asyncio reads and send()s the file manually when native sendfile is impossible.
For HTTPS, don't rely on sendfile at all — stream chunks through transport.write().
Check getattr(transport, '_sendfile_compatible', None) before deciding to use sendfile.

Example fix

// before
await loop.sendfile(ssl_transport, f, offset, count)  # RuntimeError

// after
await loop.sendfile(ssl_transport, f, offset, count, fallback=True)

Defensive patterns

Strategy: fallback

Validate before calling

from asyncio import constants
mode = getattr(transport, '_sendfile_compatible', constants._SendfileMode.UNSUPPORTED)
use_sendfile = mode is not constants._SendfileMode.UNSUPPORTED

Try / catch

try:
    sent = await loop.sendfile(transport, f, offset, count, fallback=False)
except (RuntimeError, Exception):
    sent = await loop.sendfile(transport, f, offset, count, fallback=True)

Prevention

Pass fallback=True whenever the transport type is not guaranteed (SSL, pipes, proxies).
For HTTPS file serving, use chunked transport.write() loops instead of sendfile.
Check transport._sendfile_compatible before choosing the sendfile path.

When it happens

Trigger: Calling loop.sendfile(transport, ...) where transport is an SSL transport (start_tls result), a Read/WriteTransport over a pipe, or any custom/proxied transport lacking _sendfile_compatible. With fallback=False this RuntimeError path is distinct from SendfileNotAvailableError; UNSUPPORTED transports fail immediately.

Common situations: Serving files over HTTPS: the inner transport is SSL-wrapped and native sendfile cannot run; using asyncio.open_connection over TLS then calling sendfile; custom transports in frameworks.

Related errors

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