Investigation

After struggling for about 2 hours, I found the solution.

I inspected the EmailStr datatype, discovering that the validation raises a PydanticCustomError:

def validate_email(value: str) -> tuple[str, str]:
    """Email address validation using [email-validator](https://pypi.org/project/email-validator/).

    Returns:
        A tuple containing the local part of the email (or the name for "pretty" email addresses)
            and the normalized email.

    Raises:
        PydanticCustomError: If the email is invalid.

    Note:
        Note that:

        * Raw IP address (literal) domain parts are not allowed.
        * `"John Doe <[email protected]>"` style "pretty" email addresses are processed.
        * Spaces are striped from the beginning and end of addresses, but no error is raised.
    """
    if email_validator is None:
        import_email_validator()

    if len(value) > MAX_EMAIL_LENGTH:
        raise PydanticCustomError(
            'value_error',
            'value is not a valid email address: {reason}',
            {'reason': f'Length must not exceed {MAX_EMAIL_LENGTH} characters'},
        )

    m = pretty_email_regex.fullmatch(value)
    name: str | None = None
    if m:
        unquoted_name, quoted_name, value = m.groups()
        name = unquoted_name or quoted_name

    email = value.strip()

    try:
        parts = email_validator.validate_email(email, check_deliverability=False)
    except email_validator.EmailNotValidError as e:
        raise PydanticCustomError(
            'value_error', 'value is not a valid email address: {reason}', {'reason': str(e.args[0])}
        ) from e

    email = parts.normalized
    assert email is not None
    name = name or parts.local_part
    return name, email

Sure enough, using PydanticCustomError gets serialized under the hood by FastAPI and SQLModel, generating the correct exception. For any custom validators, use PydanticCustomError

Note: The field_validator() decorator opts to the after validation type. I suggest using the AfterValidator Annotated to ensure that your custom validation takes effect or to use the field_validator()'s default of after.

Solution Implementation

Rather than having to rewrite "value_error" as the message and reason, create a base exception and raise errors with that exception.

Custom Exception:

from pydantic_core import PydanticCustomError


class ValidationValueError(ValueError):
    """Wrapper around PydanticCustomError for custom pydantic validation"""

    def __init__(self, field: str, reason: str) -> None:
        message: str = f"value is not a valid {field}: {reason}"
        super().__init__(message)
        raise PydanticCustomError(
            "value_error",
            message,
            {"reason": reason},
        )

Updated Validator:

import re
from api.src.models.v1.errors import ValidationValueError
from api.src.utils.constants.patterns import ApiPatterns


class ApiValidators:
    @staticmethod
    def is_password_valid(value: str) -> str:
        """Checks if a password is valid and strong"""
        if len(value) < 8:
            raise ValidationValueError(
                "password",
                "password must have at least 8 characters",
            )
        if not re.search(ApiPatterns.LOWER_CASE_CHARS, value):
            raise ValidationValueError(
                "password",
                "password must have one lowercase character",
            )
        if not re.search(ApiPatterns.UPPER_CASE_CHARS, value):
            raise ValidationValueError(
                "password",
                "password must have one uppercase character",
            )
        if not re.search(ApiPatterns.DIGITS, value):
            raise ValidationValueError(
                "password",
                "password must have atleast one digit",
            )
        if not re.search(ApiPatterns.SPECIAL_CHARS, value):
            raise ValidationValueError(
                "password",
                "password must have atleast one special character",
            )

        return value

Updated Model:

from sqlmodel import SQLModel
from pydantic import AfterValidator, EmailStr
from typing import Annotated
from api.src.utils.validation import ApiValidators


class UserCreate(SQLModel):
    email: EmailStr
    password: Annotated[str, AfterValidator(ApiValidators.is_password_valid)]

I hope this helps any wandered soul on this error.

Happy programming and good luck --> voorspoed