How to gracefully handle an error in a custom Convertor?

[Apakottur]

Hello and thanks for this great project.

I'm using a Starlette Convertor according to the docs, which looks something like this:

from starlette.convertors import Convertor

class MyConvertor(Convertor[str]):
    regex = r"[a-zA-Z]+"

    @override
    def convert(self, value: str) -> str:
        if some_condition_on_value(value):
            return value
        raise ValueError(f"Invalid value: {value}")

I want to allow some values but deny others, and I cannot reflect that in the regex (as it might depend on some dynamic logic)
When an invalid value is passed in this parameter, the server returns 500 and I get this trace:

../../.venv/lib/python3.14/site-packages/starlette/applications.py:90: in __call__
    await self.middleware_stack(scope, receive, send)
../../.venv/lib/python3.14/site-packages/starlette/middleware/errors.py:186: in __call__
    raise exc
../../.venv/lib/python3.14/site-packages/starlette/middleware/errors.py:164: in __call__
    await self.app(scope, receive, _send)
../../.venv/lib/python3.14/site-packages/starlette/middleware/cors.py:88: in __call__
    await self.app(scope, receive, send)
../../.venv/lib/python3.14/site-packages/starlette/middleware/authentication.py:48: in __call__
    await self.app(scope, receive, send)
../../.venv/lib/python3.14/site-packages/starlette/middleware/exceptions.py:63: in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
../../.venv/lib/python3.14/site-packages/starlette/_exception_handler.py:53: in wrapped_app
    raise exc
../../.venv/lib/python3.14/site-packages/starlette/_exception_handler.py:42: in wrapped_app
    await app(scope, receive, sender)
../../.venv/lib/python3.14/site-packages/starlette/routing.py:660: in __call__
    await self.middleware_stack(scope, receive, send)
../../.venv/lib/python3.14/site-packages/starlette/routing.py:677: in app
    match, child_scope = route.matches(scope)
                         ^^^^^^^^^^^^^^^^^^^^
../../.venv/lib/python3.14/site-packages/starlette/routing.py:246: in matches
    matched_params[key] = self.param_convertors[key].convert(value)

Is it possible to return a 4xx somehow, if the call to convert() fails because the value is invalid?
Or handle this kind of issue gracefully in another way?

Python 3.14
Starlette 1.0.0

[EmmanuelNiyonshuti]

I think that's expected behavior! starlette doesn't handle exceptions in route matching, so raising inside convert() will just spike up and throw a 500 at you. You can move the validation into the route handler and raise an HTTPException there instead. If the handler really isn't an option, you can raise an HTTPException directly inside convert() instead of a ValueError and it will work.

[Apakottur]

Raising an HTTPException from convert() sounds reasonable.
If that's valid / recommended behavior then maybe it's worth adding it into the docs?

[EmmanuelNiyonshuti]

No, I wouldn't say it's the recommended way! I just figured it could work as a workaround when I was trying to reproduce your issue. Raising HTTPException in your convertor just happens to bubble up through the middleware stack. To my knowledge convertors are really meant for type coercion not validation, so I don't think it makes sense to add to the docs.

[Kludex]

I think the "problem" is that the convertor system only supports regexes, and that's the layer that would actually perform this kind of validation ideally.

[Apakottur]

I agree that regex matching would be best but I wonder if it's powerful enough.
Even if we take the example from the docs:

from datetime import datetime

from starlette.convertors import Convertor, register_url_convertor

class DateTimeConvertor(Convertor):
    regex = "[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(.[0-9]+)?"

    def convert(self, value: str) -> datetime:
        return datetime.strptime(value, "%Y-%m-%dT%H:%M:%S")

    def to_string(self, value: datetime) -> str:
        return value.strftime("%Y-%m-%dT%H:%M:%S")

register_url_convertor("datetime", DateTimeConvertor())

Will this not return a 500 on dates like 2023-50-50T12:00:00? Is that the desired behavior?

The regex could probably be updated to handle different month lengths and leap years, but it seems much more complicated than just calling the convertor function and seeing if it "allows" it.

[MukundaKatta]

Raising from convert() surfaces as a 500 because convertors run during route matching, before exception handlers kick in. Cleanest pattern: let the convertor accept the value (or tighten regex) and do the semantic check inside the route handler, raising HTTPException(404) from there. If you actually want "no match, try next route", encode the constraint in regex itself since that's what the router respects.