BerriAI/litellm · error · Exception

invalid LAGO_API_CHARGE_BY set

Error message

invalid LAGO_API_CHARGE_BY set

What it means

Exception raised by the Lago integration when LAGO_API_CHARGE_BY is set but its value is not one of the allowed literals: end_user_id, user_id, team_id. It guards the mapping that decides which request identity becomes the Lago external customer id.

Source

Thrown at litellm/integrations/lago.py:97

        litellm_params: Final = kwargs.get("litellm_params", {}) or {}
        proxy_server_request: Final = litellm_params.get("proxy_server_request") or {}
        end_user_id: Final = proxy_server_request.get("body", {}).get("user", None)
        user_id: Final = litellm_params["metadata"].get("user_api_key_user_id", None)
        team_id: Final = litellm_params["metadata"].get("user_api_key_team_id", None)
        litellm_params["metadata"].get("user_api_key_org_id", None)

        charge_by: Literal["end_user_id", "team_id", "user_id"] = "end_user_id"
        external_customer_id: str | None = None

        if os.getenv("LAGO_API_CHARGE_BY", None) is not None and isinstance(os.environ["LAGO_API_CHARGE_BY"], str):
            if os.environ["LAGO_API_CHARGE_BY"] in [
                "end_user_id",
                "user_id",
                "team_id",
            ]:
                charge_by = os.environ["LAGO_API_CHARGE_BY"]
            else:
                raise Exception("invalid LAGO_API_CHARGE_BY set")

        if charge_by == "end_user_id":
            external_customer_id = end_user_id
        elif charge_by == "team_id":
            external_customer_id = team_id
        elif charge_by == "user_id":
            external_customer_id = user_id

        if external_customer_id is None:
            raise Exception(
                f"External Customer ID is not set. Charge_by={charge_by}. User_id={user_id}. End_user_id={end_user_id}. Team_id={team_id}"
            )

        returned_val: Final = {
            "event": {
                "transaction_id": str(uuid.uuid4()),
                "external_subscription_id": external_customer_id,
                "code": os.getenv("LAGO_API_EVENT_CODE"),

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Set LAGO_API_CHARGE_BY to exactly one of: end_user_id, user_id, team_id
2. Remove the variable entirely if the default end_user_id is acceptable
3. Check docker-compose/k8s env entries for injected quotes or trailing whitespace

Example fix

# before
LAGO_API_CHARGE_BY=end-user-id  # hyphens invalid

# after
LAGO_API_CHARGE_BY=end_user_id

import os

VALID = {"end_user_id", "user_id", "team_id"}
val = os.getenv("LAGO_API_CHARGE_BY")
if val is not None and val not in VALID:
    raise RuntimeError(f"LAGO_API_CHARGE_BY must be one of {sorted(VALID)}, got {val!r}")

from typing import Literal

def is_valid_charge_by(value: str | None) -> bool:
    return value is None or value in {"end_user_id", "user_id", "team_id"}

When it happens

Trigger: Setting LAGO_API_CHARGE_BY to any other string — e.g. 'end-user-id' (hyphens), 'customer_id', 'organization', or with stray whitespace/quotes — in the environment of a process with the lago callback enabled.

Common situations: Config typo like END_USER_ID or hyphenated end-user-id; copying a value from docs of a different Lago SDK; values stored with surrounding quotes in YAML/docker-compose env entries.

Related errors

• Missing keys={missing_keys} in environment.
• External Customer ID is not set. Charge_by={charge_by}. User
• Error: {response.status_code} - {response.text}
• Missing Authorization header
• Invalid bearer token

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