BerriAI/litellm · error · BlackForestLabsError

BFL_API_KEY is not set. Please set it via environment…

Error message

BFL_API_KEY is not set. Please set it via environment variable or pass api_key parameter.

What it means

Before any BFL request, validate_environment resolves the key as api_key argument, then BFL_API_KEY, then BLACK_FOREST_LABS_API_KEY secrets. If all are empty it raises BlackForestLabsError 401 with this message. BFL authenticates with the x-key header, which cannot be set without a key.

Solutions

export BFL_API_KEY=... (or BLACK_FOREST_LABS_API_KEY) in the process that runs LiteLLM.
Or pass api_key explicitly: litellm.image_generation(..., api_key=KEY).
In LiteLLM proxy, set the env var on the proxy host/container or configure it via the model's environment settings.
Verify with print(os.environ.get('BFL_API_KEY')) inside the same process.

Example fix

# before
litellm.image_generation(model="black_forest_labs/flux-pro-1.1", prompt="a cat")

# after
litellm.image_generation(
    model="black_forest_labs/flux-pro-1.1",
    prompt="a cat",
    api_key=os.environ["BFL_API_KEY"],
)

Defensive patterns

Strategy: validation

Validate before calling

import os

def bfl_key_available() -> bool:
    return bool(
        os.environ.get("BFL_API_KEY")
        or os.environ.get("BLACK_FOREST_LABS_API_KEY")
        or os.environ.get("BFL_API_KEY_FALLBACK")  # wherever you inject keys
    )

Try / catch

from litellm.llms.black_forest_labs.common_utils import BlackForestLabsError

try:
    litellm.image_generation(model="black_forest_labs/flux-pro-1.1", prompt=p)
except BlackForestLabsError as e:
    if e.status_code == 401 and "BFL_API_KEY" in str(e):
        raise RuntimeError("BFL credentials missing — set BFL_API_KEY") from e
    raise

Prevention

Fail fast at startup: assert the key env var is present before serving traffic.
Pass api_key explicitly from your secret manager rather than relying on ambient env.
Name keys exactly BFL_API_KEY / BLACK_FOREST_LABS_API_KEY.

When it happens

Trigger: Calling litellm.image_generation(model="black_forest_labs/...") with neither api_key passed nor BFL_API_KEY/BLACK_FOREST_LABS_API_KEY exported; env var typo (e.g. BFL_APIKEY); key defined in a shell but not in the process running the LiteLLM proxy/server; .env file not loaded.

Common situations: CI jobs and containers missing the env var; proxy deployments where the key must be set in the environment of the proxy process, not the caller; local works (exported in shell) but systemd/docker service fails; secret manager name mismatch.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at litellm/llms/black_forest_labs/image_generation/transformation.py:159

        headers: dict,
        model: str,
        messages: list[AllMessageValues],
        optional_params: dict,
        litellm_params: dict,
        api_key: str | None = None,
        api_base: str | None = None,
    ) -> dict:
        """
        Validate environment and set up headers for Black Forest Labs.

        BFL uses x-key header for authentication.
        """
        final_api_key: Final[str | None] = (
            api_key or get_secret_str("BFL_API_KEY") or get_secret_str("BLACK_FOREST_LABS_API_KEY")
        )

        if not final_api_key:
            raise BlackForestLabsError(
                status_code=401,
                message="BFL_API_KEY is not set. Please set it via environment variable or pass api_key parameter.",
            )

        headers["x-key"] = final_api_key
        headers["Content-Type"] = "application/json"
        headers["Accept"] = "application/json"

        return headers

    def _get_model_endpoint(self, model: str) -> str:
        """
        Get the API endpoint for a given model.
        """
        # Remove provider prefix if present (e.g., "black_forest_labs/flux-pro-1.1")
        model_name = model.lower()
        if "/" in model_name:
            model_name = model_name.split("/")[-1]

View on GitHub (pinned to 77b7c6c40c)