BerriAI/litellm · critical · BlackForestLabsError

BFL_API_KEY is not set. Please set it via environment variab

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 API key from (in order) the explicit api_key argument, BFL_API_KEY, or BLACK_FOREST_LABS_API_KEY secrets. If none is found, this BlackForestLabsError (HTTP 401) is raised. It fires before any network traffic, purely from missing configuration.

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 6c2dcb801b)

Solutions

export BFL_API_KEY=<your key> (or BLACK_FOREST_LABS_API_KEY) in the environment running litellm.
Or pass the key explicitly: litellm.images.generate(..., api_key=<key>).
In server deployments, add it to the litellm proxy environment config / secrets manager so workers inherit it.
Verify with: python -c "from litellm import get_secret_str; print(bool(get_secret_str('BFL_API_KEY')))"

Example fix

# before
litellm.images.generate(model="black_forest_labs/flux-pro-1.1", prompt=p)

# after
litellm.images.generate(model="black_forest_labs/flux-pro-1.1", prompt=p, api_key=os.environ["BFL_API_KEY"])

Defensive patterns

Strategy: validation

Validate before calling

from litellm import get_secret_str

if not (get_secret_str("BFL_API_KEY") or get_secret_str("BLACK_FOREST_LABS_API_KEY")):
    raise RuntimeError("Configure BFL_API_KEY before starting the service")

Try / catch

try:
    resp = litellm.images.generate(model="bfl/flux-pro-1.1", prompt=p)
except BlackForestLabsError as e:
    if e.status_code == 401 and "BFL_API_KEY is not set" in str(e):
        fail_fast_config_error("missing BFL_API_KEY")  # alert ops, do not retry
    raise

Prevention

Fail fast at startup: check required provider keys in a boot-time config check.
In proxies, declare required env vars in deployment manifests so missing keys block deploy, not requests.
Run a smoke image request in staging after key rotation.

When it happens

Trigger: Calling a bfl model with no api_key parameter while neither BFL_API_KEY nor BLACK_FOREST_LABS_API_KEY is present in the process environment / secret store.

Common situations: Forgotten env var in a new deploy or CI job; .env file not loaded; key set under a different name (e.g. only OPENAI_API_KEY); virtualenv/container where the variable wasn't exported; typos in the variable name.

Related errors

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