BerriAI/litellm · error · ValueError

CloudZero configuration missing. Please set…

Error message

CloudZero configuration missing. Please set CLOUDZERO_API_KEY and CLOUDZERO_CONNECTION_ID environment variables.

What it means

ValueError raised by the CloudZero logger's export_usage_data when self.api_key or self.connection_id is falsy — i.e. neither the callback config nor the environment provided CLOUDZERO_API_KEY and CLOUDZERO_CONNECTION_ID. It fires at the start of an export run, before any database query or API call, and names both required variables.

Solutions

Set both variables in the proxy runtime: export CLOUDZERO_API_KEY=... and export CLOUDZERO_CONNECTION_ID=...
If using the callback config, pass the values there instead (litellm_params on the cloudzero callback)
Restart the LiteLLM proxy after setting them — config is read at logger init
Verify in the exact runtime: printenv CLOUDZERO_API_KEY CLOUDZERO_CONNECTION_ID (both non-empty)

Example fix

# before
$ docker run litellm/litellm ...   # env not passed

# after
$ docker run -e CLOUDZERO_API_KEY -e CLOUDZERO_CONNECTION_ID litellm/litellm ...

Defensive patterns

Strategy: validation

Validate before calling

import os

missing = [v for v in ("CLOUDZERO_API_KEY", "CLOUDZERO_CONNECTION_ID") if not os.getenv(v)]
if missing:
    raise RuntimeError(f"cannot export to CloudZero; missing env vars: {missing}")

Prevention

Declare both CLOUDZERO_API_KEY and CLOUDZERO_CONNECTION_ID in the deployment spec (Deployment env / docker -e)
Add a preflight check in the export job that fails loudly before querying usage data
Verify with printenv in the exact runtime after deploys
Watch for empty-string values — falsy counts as missing here

When it happens

Trigger: Triggering the CloudZero usage export (scheduled cron inside the proxy or the export endpoint/job) while one or both of CLOUDZERO_API_KEY / CLOUDZERO_CONNECTION_ID are unset or empty in the proxy's environment. Values set only in a local .env, a typo'd name, or a restarted container that lost env config all trigger it.

Common situations: Docker/Kubernetes deployments missing the env entries; secrets renamed or removed; CI running export jobs without injecting credentials; trailing quotes/spaces making a variable technically set but the connection_id empty.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at litellm/integrations/cloudzero/cloudzero.py:120

        - Reads data from the DB
        - Transforms the data to the CloudZero format
        - Sends the data to CloudZero

        Args:
            limit: Optional limit on number of records to export
            operation: CloudZero operation type ("replace_hourly" or "sum")
        """
        from litellm.integrations.cloudzero.cz_stream_api import CloudZeroStreamer
        from litellm.integrations.cloudzero.database import LiteLLMDatabase
        from litellm.integrations.cloudzero.transform import CBFTransformer

        try:
            verbose_logger.debug("CloudZero Logger: Starting usage data export")

            # Validate required configuration
            if not self.api_key or not self.connection_id:
                raise ValueError(
                    "CloudZero configuration missing. Please set CLOUDZERO_API_KEY and CLOUDZERO_CONNECTION_ID environment variables."
                )

            # Initialize database connection and load data
            database: Final = LiteLLMDatabase()
            verbose_logger.debug("CloudZero Logger: Loading usage data from database")
            data = await database.get_usage_data(limit=limit, start_time_utc=start_time_utc, end_time_utc=end_time_utc)

            if data.is_empty():
                verbose_logger.debug("CloudZero Logger: No usage data found to export")
                return

            verbose_logger.debug("CloudZero Logger: Processing %s records", len(data))

            # Transform data to CloudZero CBF format
            transformer: Final = CBFTransformer()
            cbf_data: Final = transformer.transform(data)

View on GitHub (pinned to 77b7c6c40c)