BerriAI/litellm · error · Exception

OpenMeter: user is required

Error message

OpenMeter: user is required

What it means

OpenMeter events require a subject (end user) for metering. _common_logic tries kwargs['user'] (only when trust_request_user is enabled) and then the virtual-key metadata user_api_key_user_id; if neither exists it raises. OpenMeter's billing/metering model is per-subject, so an anonymous event is not representable.

Source

Thrown at litellm/integrations/openmeter.py:84

        # OPENMETER_TRUST_REQUEST_USER (default "true"): when set to "false",
        # the request-supplied `user` field is ignored and the subject is
        # resolved solely from the key-bound user_api_key_user_id. Proxies
        # serving multi-tenant traffic enable this to prevent clients from
        # forging attribution by setting `user` in the request body.
        trust_request_user: Final = os.getenv("OPENMETER_TRUST_REQUEST_USER", "true").lower() != "false"
        user_param = kwargs.get("user", None) if trust_request_user else None

        # If no user provided directly, try to get it from token user_id
        if user_param is None:
            # Check if user_id is available from the API key metadata
            litellm_params: Final = kwargs.get("litellm_params", {})
            metadata: Final = litellm_params.get("metadata", {})
            user_api_key_user_id: Final = metadata.get("user_api_key_user_id", None)

            if user_api_key_user_id is not None:
                user_param = user_api_key_user_id
            else:
                raise Exception("OpenMeter: user is required")

        # Ensure subject is always a string for OpenMeter API
        subject: Final = str(user_param)

        return {
            "specversion": "1.0",
            "type": os.getenv("OPENMETER_EVENT_TYPE", "litellm_tokens"),
            "id": call_id,
            "time": dt,
            "subject": subject,
            "source": "litellm-proxy",
            "data": {"model": model, "cost": cost, **usage},
        }

    def log_success_event(self, kwargs, response_obj, start_time, end_time):
        _url = os.getenv("OPENMETER_API_ENDPOINT", "https://openmeter.cloud")
        if _url.endswith("/"):
            _url += "api/v1/events"

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass user='<user-id>' on litellm.completion / proxy requests so kwargs carries it
2. In the proxy, attach a user_id to the virtual key so metadata.user_api_key_user_id is populated (create or update the key with a user_id)
3. Enable the setting that trusts the request user if your security model allows it, so kwargs['user'] is used directly
4. If subject attribution is impossible for some traffic, route those calls to a callback set without openmeter

Example fix

# before
response = litellm.completion(model="gpt-4o", messages=[...])
# during openmeter logging: Exception: OpenMeter: user is required

# after
response = litellm.completion(
    model="gpt-4o",
    messages=[...],
    user="user-123",  # becomes the OpenMeter event subject
)

def openmeter_subject_available(kwargs: dict, trust_user: bool) -> bool:
    if trust_user and kwargs.get("user"):
        return True
    metadata = kwargs.get("litellm_params", {}).get("metadata", {})
    return metadata.get("user_api_key_user_id") is not None

When it happens

Trigger: Calling litellm.completion without user= while trust_request_user is disabled or unset; proxy requests where the virtual key has no user_id attached (user_api_key_user_id absent from metadata); programmatic API-key calls with no user context.

Common situations: Teams enabling OpenMeter mid-project before tagging requests with users; proxy keys created without an owner user_id; clients that never send a user field.

Related errors

• Langfuse not installed, try running 'pip install langfu
• Max langfuse clients reached: {litellm.initialized_langfuse_
• Error logging request payload. Payload=none.
• standard_logging_object not found in kwargs
• Missing keys={missing_keys} in environment.

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/a52696d19c5a073d. Report an issue: GitHub.