What causes "Unsupported order {order!r}" in aio-libs/aiohttp?

Import and use the Order enum: `from aiohttp.payload import Order` and pass `order=Order.try_first`.

aio-libs/aiohttp · error · ValueError

Unsupported order {order!r}

Error message

Unsupported order {order!r}

What it means

Raised by PayloadRegistry.register() when the `order` argument is not one of the Order enum members (try_first, normal, try_last). This is an internal/library-extension error: register() dispatches on the enum value and the final else branch rejects anything unrecognized.

Source

Thrown at aiohttp/payload.py:137

                return factory(data, *args, **kwargs)
        raise LookupError()

    def register(
        self, factory: PayloadType, type: Any, *, order: Order = Order.normal
    ) -> None:
        if order is Order.try_first:
            self._first.append((factory, type))
        elif order is Order.normal:
            self._normal.append((factory, type))
            if isinstance(type, Iterable):
                for t in type:
                    self._normal_lookup[t] = factory
            else:
                self._normal_lookup[type] = factory
        elif order is Order.try_last:
            self._last.append((factory, type))
        else:
            raise ValueError(f"Unsupported order {order!r}")


class Payload(ABC):
    _default_content_type: str = "application/octet-stream"
    _size: int | None = None
    _consumed: bool = False  # Default: payload has not been consumed yet
    _autoclose: bool = False  # Default: assume resource needs explicit closing

    def __init__(
        self,
        value: Any,
        headers: (
            CIMultiDict[str] | dict[str, str] | Iterable[tuple[str, str]] | None
        ) = None,
        content_type: None | str | _SENTINEL = sentinel,
        filename: str | None = None,
        encoding: str | None = None,
        **kwargs: Any,

View on GitHub (pinned to c0ef574e29)

Solutions

Import and use the Order enum: `from aiohttp.payload import Order` and pass `order=Order.try_first`.
Omit the order argument — it defaults to Order.normal which is always valid.
Ensure you are not passing a plain string; compare against Order members.

Example fix

// before
payload.register(Factory, MyType, order='first')  # -> ValueError
// after
from aiohttp.payload import Order
payload.register(Factory, MyType, order=Order.try_first)

Defensive patterns

Strategy: validation

Validate before calling

from aiohttp.payload import Order
if order not in Order.__members__.values():
    raise ValueError(f'order must be an Order member, got {order!r}')

Type guard

from aiohttp.payload import Order

def is_valid_order(order) -> bool:
    return order in Order.__members__.values()

Try / catch

try:
    payload.register(Factory, MyType, order=order)
except ValueError:
    payload.register(Factory, MyType, order=Order.normal)

Prevention

Always pass an Order enum member, not a string.
Default to Order.normal when in doubt.
Add a unit test for custom payload registrations.

When it happens

Trigger: Calling `payload.register(MyFactory, MyType, order=<something>)` where <something> is not an Order enum member — e.g. a raw string like 'first', an int, or None. Only happens when extending aiohttp's payload registry with a custom factory.

Common situations: Writing a third-party integration that registers a custom Payload type; passing a string instead of Order.try_first by mistake; typo in the enum member name.

Related errors

AI-assisted analysis of aio-libs/aiohttp@c0ef574e29 (2026-08-04). Data as JSON: /data/errors/891dedb05136bedb.json. Report an issue: GitHub.