psf/requests · warning · ValueError

Unsupported event specified, with event name

Error message

Unsupported event specified, with event name "{event}"

What it means

Raised by RequestHooksMixin.register_hook when the event name is not already a key in the hooks dict. requests pre-populates hooks with a fixed set of event names (e.g. 'response'); registering a hook against any other event name is rejected because the dispatcher will never fire it. This prevents silently-ignored hooks caused by typos or speculative event names.

Solutions

Use one of the canonical events supported by requests — currently 'response' is the primary hook event. Check Session.hooks / Request.hooks keys for the exact set in your version.
Inspect the existing hooks dict (print(request.hooks)) before registering to see accepted event names.
If you need custom event dispatch, layer your own pub/sub on top rather than reusing requests' hooks dict.

Example fix

// before
request.register_hook('error', my_handler)

// after
request.register_hook('response', my_handler)

Defensive patterns

Strategy: validation

Validate before calling

from requests import Request

SUPPORTED_HOOK_EVENTS = {'response'}

def safe_register(req: Request, event: str, hook):
    if event not in SUPPORTED_HOOK_EVENTS:
        raise ValueError(f'unsupported hook event: {event!r}; supported: {SUPPORTED_HOOK_EVENTS}')
    req.register_hook(event, hook)

Type guard

SUPPORTED_HOOK_EVENTS = {'response'}

def is_supported_hook_event(event: str) -> bool:
    return event in SUPPORTED_HOOK_EVENTS

Try / catch

try:
    request.register_hook(event, hook)
except ValueError:
    # unknown event; ignore or log
    pass

Prevention

Use only the canonical events (currently 'response').
Inspect request.hooks keys before registering.
Build your own pub/sub for custom events rather than reusing requests' hooks dict.

When it happens

Trigger: Calling request.register_hook('responce', fn) with a typo; inventing an event name like 'request' or 'error' that requests does not emit; passing an event from a config file that does not match the canonical hook names.

Common situations: Copy-pasting hook code from a tutorial that uses an outdated or invented event name; building a generic hooks framework on top of requests and assuming arbitrary events are supported.

Related errors

AI-assisted analysis of psf/requests@8068356288 (2026-08-11). Data as JSON: /api/errors/ed0968e65e56e8b0. Report an issue: GitHub.

Appendix: source

Thrown at src/requests/models.py:263

            rf = RequestField(name=k, data=fdata, filename=fn, headers=fh)
            rf.make_multipart(content_type=ft)
            new_fields.append(rf)

        body, content_type = encode_multipart_formdata(new_fields)

        return body, content_type


class RequestHooksMixin:
    hooks: dict[str, list[_t.HookType]]

    def register_hook(
        self, event: str, hook: Iterable[_t.HookType] | _t.HookType
    ) -> None:
        """Properly register a hook."""

        if event not in self.hooks:
            raise ValueError(f'Unsupported event specified, with event name "{event}"')

        if isinstance(hook, Callable):
            self.hooks[event].append(hook)
        elif hasattr(hook, "__iter__"):
            self.hooks[event].extend(
                h for h in hook if isinstance(h, Callable)
            )  # defensive runtime filter

    def deregister_hook(self, event: str, hook: _t.HookType) -> bool:
        """Deregister a previously registered hook.
        Returns True if the hook existed, False if not.
        """

        try:
            self.hooks[event].remove(hook)
            return True
        except ValueError:
            return False

View on GitHub (pinned to 8068356288)