BerriAI/litellm · error · ValueError

timeout must be numeric, got {v!r}

Error message

timeout must be numeric, got {v!r}

What it means

Pydantic field_validator coercing the guardrail timeout: the dashboard UI sends JSON string timeouts, and a value arrived that is neither None, empty, nor numeric-coercible, so it cannot be converted to float.

Source

Thrown at litellm/types/guardrails.py:1018

    VigilGuardGuardrailConfigModel,
    SingulrGuardrailConfigModel,
):
    guardrail: str = Field(description="The type of guardrail integration to use")
    mode: str | list[str] | Mode = Field(
        description="When to apply the guardrail (pre_call, post_call, during_call, logging_only)"
    )

    @field_validator("timeout", mode="before", check_fields=False)
    @classmethod
    def coerce_timeout(cls, v):
        """Accept string-valued timeouts (dashboard UI sends JSON strings)
        and coerce to float before any handler reads the value."""
        if v is None or v == "":
            return None
        try:
            return float(v)
        except (TypeError, ValueError) as e:
            raise ValueError(f"timeout must be numeric, got {v!r}") from e

    def __init__(self, **kwargs) -> None:
        default_on: Final = kwargs.pop("default_on", None)
        if default_on is not None:
            kwargs["default_on"] = default_on
        else:
            kwargs["default_on"] = False

        super().__init__(**kwargs)

    def __contains__(self, key) -> bool:
        # Define custom behavior for the 'in' operator
        return hasattr(self, key)

    def get(self, key, default=None):
        # Custom .get() method to access attributes with a default value if the attribute doesn't exist
        return getattr(self, key, default)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass a numeric timeout (int/float seconds), not {v!r}.
2. Parse string input with float() before validation.

When it happens

Trigger: Thrown at litellm/types/guardrails.py:1018 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/21c158d7d9202040. Report an issue: GitHub.