BerriAI/litellm · error · Exception

'litellm.argilla_transformation_object' is required, to log…

Error message

'litellm.argilla_transformation_object' is required, to log your payload to Argilla.

What it means

The ArgillaLogger is LiteLLM's callback that ships logged LLM calls to an Argilla dataset. It is configured entirely through the module-level `litellm.argilla_transformation_object`, which maps your logging payload keys to Argilla fields. The logger refuses to initialize if that object is None, because without it there is no way to transform request/response data into Argilla records.

Solutions

Set the transformation object before the logger initializes, e.g. `litellm.argilla_transformation_object = {"model": "model", "prompt": "messages", "response": "response"}` (keys map your payload, values must be from SUPPORTED_PAYLOAD_FIELDS)
Then enable the callback: `litellm.callbacks = ["argilla"]` (or add `callbacks: ["argilla"]` in proxy config with the transformation object set via litellm_settings)
Verify assignment happens before any completion call, since callback loggers initialize lazily at first use

Example fix

# before
import litellm
litellm.callbacks = ["argilla"]  # Exception: 'litellm.argilla_transformation_object' is required

# after
import litellm
litellm.argilla_transformation_object = {
    "model": "model",
    "prompt": "messages",
    "response": "response",
}
litellm.callbacks = ["argilla"]

Defensive patterns

Strategy: validation

Validate before calling

import litellm

def configure_argilla(mapping: dict) -> None:
    if not mapping:
        raise ValueError("argilla_transformation_object must be a non-empty dict")
    litellm.argilla_transformation_object = mapping
    litellm.callbacks = ["argilla"]

configure_argilla({"prompt": "messages", "response": "response"})

Type guard

def is_valid_argilla_config(obj: object) -> bool:
    from litellm.types.integrations.argilla import SUPPORTED_PAYLOAD_FIELDS
    return (
        isinstance(obj, dict)
        and len(obj) > 0
        and all(v in SUPPORTED_PAYLOAD_FIELDS for v in obj.values())
    )

Try / catch

try:
    litellm.callbacks = ["argilla"]
except Exception as e:
    if "argilla_transformation_object" in str(e):
        # config incomplete: disable argilla logging and continue without it
        litellm.callbacks = [c for c in (litellm.callbacks or []) if c != "argilla"]
        log.warning("Argilla disabled: %s", e)
    else:
        raise

Prevention

Centralize argilla setup in one function that sets transformation object, API key, and callback together
Run a smoke completion call in staging right after enabling callbacks to surface init errors early

When it happens

Trigger: Setting `litellm.settings.callbacks = ["argilla"]` (or `litellm.callbacks = ["argilla"]`) / using `--callbacks argilla` in proxy config without first assigning `litellm.argilla_transformation_object = {...}`. ArgillaLogger.__init__ reads `litellm.argilla_transformation_object`, finds None, and raises.

Common situations: Copy-pasting a proxy config snippet that enables the argilla callback but omitting the transformation_object lines; enabling the callback before the assignment runs (import-order issues); upgrading litellm and assuming argilla is configured via env vars only.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at litellm/integrations/argilla.py:50

    non_serializable_types: Final = (
        types.CoroutineType,
        types.FunctionType,
        types.GeneratorType,
        BaseModel,
    )
    return not isinstance(value, non_serializable_types)


class ArgillaLogger(CustomBatchLogger):
    def __init__(
        self,
        argilla_api_key: str | None = None,
        argilla_dataset_name: str | None = None,
        argilla_base_url: str | None = None,
        **kwargs,
    ):
        if litellm.argilla_transformation_object is None:
            raise Exception("'litellm.argilla_transformation_object' is required, to log your payload to Argilla.")
        self.validate_argilla_transformation_object(litellm.argilla_transformation_object)
        self.argilla_transformation_object = litellm.argilla_transformation_object
        self.default_credentials = self.get_credentials_from_env(
            argilla_api_key=argilla_api_key,
            argilla_dataset_name=argilla_dataset_name,
            argilla_base_url=argilla_base_url,
        )
        self.sampling_rate: float = (
            float(os.getenv("ARGILLA_SAMPLING_RATE"))
            if os.getenv("ARGILLA_SAMPLING_RATE") is not None and os.getenv("ARGILLA_SAMPLING_RATE").strip().isdigit()
            else 1.0
        )

        self.async_httpx_client = get_async_httpx_client(llm_provider=httpxSpecialProvider.LoggingCallback)
        _batch_size: Final = os.getenv("ARGILLA_BATCH_SIZE", None) or litellm.argilla_batch_size
        if _batch_size:
            self.batch_size = int(_batch_size)
        asyncio.create_task(self.periodic_flush())

View on GitHub (pinned to 77b7c6c40c)