psf/requests · error · ValueError

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

Error message

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

What it means

Raised by `RequestHooksMixin.register_hook` when the `event` name is not a key in the object's `hooks` dict. Requests only dispatches a fixed set of hook events (in practice just `"response"`, initialized by `default_hooks()`), so registering a hook for any other event name would silently never fire — the ValueError fails fast instead.

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 414f0513c3)

Solutions

1. Use the only supported event name, 'response': `hooks={'response': my_hook}`.
2. For pre-send behavior, subclass `requests.adapters.HTTPAdapter` or use a Session with a custom `prepare_request` wrapper instead of a hook.
3. Check `request.hooks.keys()` (from `requests.hooks.default_hooks()`) to see the valid event names for your version.

Example fix

# before
requests.get(url, hooks={'pre_request': log_hook})

# after
requests.get(url, hooks={'response': log_hook})

VALID_HOOKS = {"response"}  # requests only supports the 'response' hook
assert all(k in VALID_HOOKS for k in hooks), f"invalid hook events: {set(hooks) - VALID_HOOKS}"

try:
    resp = requests.get(url, hooks={"response": my_hook})
except ValueError as e:
    if "Unsupported event" in str(e):
        ...  # misspelled or unsupported hook name
    raise

When it happens

Trigger: `requests.get(url, hooks={'pre_request': fn})` or `session.hooks` / `Request(hooks={...})` with any key other than 'response'; calling `req.register_hook('request', fn)` directly. The hooks dict passed to the Request constructor is registered event-by-event, so one bad key raises.

Common situations: Code ported from very old requests versions (pre-1.0 supported events like 'pre_request', 'args', 'post_request' that were removed); typos like 'reponse'; assuming a richer event model similar to other HTTP libraries' middleware.

Related errors

• Files must be provided.
• Data must not be a string.
• Invalid URL {url!r}: No scheme supplied. Perhaps you meant h
• Invalid URL {url!r}: No host supplied
• URL has an invalid label.

AI-assisted analysis of psf/requests@414f0513c3 (2026-07-31). Data as JSON: /data/errors/ed0968e65e56e8b0.json. Report an issue: GitHub ↗.