{"record":{"id":"8ec6561db4194570","repo":"BerriAI/litellm","slug":"litellm-argilla-transformation-object-is-require","errorCode":null,"errorMessage":"'litellm.argilla_transformation_object' is required, to log your payload to Argilla.","messagePattern":"'litellm\\.argilla_transformation_object' is required, to log your payload to Argilla\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"litellm/integrations/argilla.py","lineNumber":50,"sourceCode":"    non_serializable_types: Final = (\n        types.CoroutineType,\n        types.FunctionType,\n        types.GeneratorType,\n        BaseModel,\n    )\n    return not isinstance(value, non_serializable_types)\n\n\nclass ArgillaLogger(CustomBatchLogger):\n    def __init__(\n        self,\n        argilla_api_key: str | None = None,\n        argilla_dataset_name: str | None = None,\n        argilla_base_url: str | None = None,\n        **kwargs,\n    ):\n        if litellm.argilla_transformation_object is None:\n            raise Exception(\"'litellm.argilla_transformation_object' is required, to log your payload to Argilla.\")\n        self.validate_argilla_transformation_object(litellm.argilla_transformation_object)\n        self.argilla_transformation_object = litellm.argilla_transformation_object\n        self.default_credentials = self.get_credentials_from_env(\n            argilla_api_key=argilla_api_key,\n            argilla_dataset_name=argilla_dataset_name,\n            argilla_base_url=argilla_base_url,\n        )\n        self.sampling_rate: float = (\n            float(os.getenv(\"ARGILLA_SAMPLING_RATE\"))\n            if os.getenv(\"ARGILLA_SAMPLING_RATE\") is not None and os.getenv(\"ARGILLA_SAMPLING_RATE\").strip().isdigit()\n            else 1.0\n        )\n\n        self.async_httpx_client = get_async_httpx_client(llm_provider=httpxSpecialProvider.LoggingCallback)\n        _batch_size: Final = os.getenv(\"ARGILLA_BATCH_SIZE\", None) or litellm.argilla_batch_size\n        if _batch_size:\n            self.batch_size = int(_batch_size)\n        asyncio.create_task(self.periodic_flush())","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/integrations/argilla.py#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nimport litellm\nlitellm.callbacks = [\"argilla\"]  # Exception: 'litellm.argilla_transformation_object' is required\n\n# after\nimport litellm\nlitellm.argilla_transformation_object = {\n    \"model\": \"model\",\n    \"prompt\": \"messages\",\n    \"response\": \"response\",\n}\nlitellm.callbacks = [\"argilla\"]","handlingStrategy":"validation","validationCode":"import litellm\n\ndef configure_argilla(mapping: dict) -> None:\n    if not mapping:\n        raise ValueError(\"argilla_transformation_object must be a non-empty dict\")\n    litellm.argilla_transformation_object = mapping\n    litellm.callbacks = [\"argilla\"]\n\nconfigure_argilla({\"prompt\": \"messages\", \"response\": \"response\"})","typeGuard":"def is_valid_argilla_config(obj: object) -> bool:\n    from litellm.types.integrations.argilla import SUPPORTED_PAYLOAD_FIELDS\n    return (\n        isinstance(obj, dict)\n        and len(obj) > 0\n        and all(v in SUPPORTED_PAYLOAD_FIELDS for v in obj.values())\n    )","tryCatchPattern":"try:\n    litellm.callbacks = [\"argilla\"]\nexcept Exception as e:\n    if \"argilla_transformation_object\" in str(e):\n        # config incomplete: disable argilla logging and continue without it\n        litellm.callbacks = [c for c in (litellm.callbacks or []) if c != \"argilla\"]\n        log.warning(\"Argilla disabled: %s\", e)\n    else:\n        raise","preventionTips":["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"],"tags":["argilla","callback","configuration","logging"],"backgroundTag":"missing-required-config","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}