BerriAI/litellm · error · ValueError

PROMETHEUS_URL not set please set 'PROMETHEUS_URL=<>' in .en

Error message

PROMETHEUS_URL not set please set 'PROMETHEUS_URL=<>' in .env

What it means

get_metric_from_prometheus queries the Prometheus HTTP API for the last 24h of a metric, but refuses to run unless the PROMETHEUS_URL secret/env var is set at import time (litellm.integrations.prometheus_helpers.prometheus_api reads it via get_secret at module load). The ValueError is raised at call time when that module-level value is None.

Source

Thrown at litellm/integrations/prometheus_helpers/prometheus_api.py:27

from litellm import get_secret
from litellm._logging import verbose_logger
from litellm.llms.custom_httpx.http_handler import (
    get_async_httpx_client,
    httpxSpecialProvider,
)

PROMETHEUS_URL: Final[str | None] = get_secret("PROMETHEUS_URL")
PROMETHEUS_SELECTED_INSTANCE: Final[str | None] = get_secret("PROMETHEUS_SELECTED_INSTANCE")
async_http_handler: Final = get_async_httpx_client(llm_provider=httpxSpecialProvider.LoggingCallback)


async def get_metric_from_prometheus(
    metric_name: str,
):
    # Get the start of the current day in Unix timestamp
    if PROMETHEUS_URL is None:
        raise ValueError("PROMETHEUS_URL not set please set 'PROMETHEUS_URL=<>' in .env")

    query: Final = f"{metric_name}[24h]"
    now: Final = int(time.time())
    response: Final = await async_http_handler.get(
        f"{PROMETHEUS_URL}/api/v1/query", params={"query": query, "time": now}
    )  # End of the day
    _json_response: Final = response.json()
    verbose_logger.debug("json response from prometheus /query api %s", _json_response)
    results: Final = response.json()["data"]["result"]
    return results


async def get_fallback_metric_from_prometheus():
    """
    Gets fallback metrics from prometheus for the last 24 hours
    """
    response_message = ""
    relevant_metrics: Final = [

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Set PROMETHEUS_URL (e.g. http://prometheus:9090) in the proxy's environment/.env and restart the process
2. If running in Docker, verify the variable is passed (docker run -e PROMETHEUS_URL=... or listed in env_file)
3. If self-hosting Prometheus, point it at the scrape target exposed by the prometheus callback port first, then set the URL

Example fix

# .env
PROMETHEUS_URL=http://prometheus:9090

# docker-compose.yaml
services:
  litellm:
    environment:
      - PROMETHEUS_URL=http://prometheus:9090

import os

PROM_URL = os.getenv("PROMETHEUS_URL")
if not PROM_URL:
    raise RuntimeError("Set PROMETHEUS_URL (e.g. http://prometheus:9090) before using prometheus queries")

results = await get_metric_from_prometheus("litellm_request_total_latency_bucket")

try:
    results = await get_metric_from_prometheus(metric)
except ValueError as e:
    if "PROMETHEUS_URL not set" in str(e):
        results = []  # metrics feature disabled
    else:
        raise

When it happens

Trigger: Calling proxy admin endpoints that surface prometheus metrics (e.g. /global/spend/report or model-metric dashboards) without PROMETHEUS_URL defined; running the proxy with prometheus callback enabled but the URL configured only in a different environment (.env not loaded, wrong container).

Common situations: Deploying the proxy with metrics scraping but forgetting the URL env var; .env present locally but not copied into Docker image; setting PROMETHEUS_URL after process start (it is read once at import, so a hot set of os.environ will not help).

Related errors

• Qdrant url must be provided
• Missing required Redis configuration: {missing_var}. Provide
• Missing required Valkey configuration. Provide host and port
• Missing keys={missing_keys} in environment.
• invalid LAGO_API_CHARGE_BY set

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