BerriAI/litellm · error · 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

The BFL image-edit transformation builds auth headers and requires an API key. It resolves the key from the explicit `api_key` parameter, then the BFL_API_KEY environment variable, then BLACK_FOREST_LABS_API_KEY. If none is present, it raises BlackForestLabsError(401) before any network call is made. This is a local configuration failure, not an upstream rejection.

Source

Thrown at litellm/llms/black_forest_labs/image_edit/transformation.py:141

    def validate_environment(
        self,
        headers: dict,
        model: str,
        api_key: str | None = None,
        litellm_params: dict | 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 use_multipart_form_data(self) -> bool:
        """
        BFL uses JSON requests, not multipart/form-data.
        """
        return False

    def _get_model_endpoint(self, model: str) -> str:
        """

View on GitHub (pinned to 6c2dcb801b)

Solutions

export BFL_API_KEY=<your key> in the environment where LiteLLM runs, then retry.
Or pass the key explicitly: litellm.image_edit(..., api_key=...).
On the LiteLLM proxy, add the key to the model's litellm_params (api_key: os.environ/BFL_API_KEY) and ensure the env var is present in the proxy's environment.
As a fallback name, BLACK_FOREST_LABS_API_KEY is also accepted if BFL_API_KEY is unset.

Example fix

# before
litellm.image_edit(model="black_forest_labs/flux-kontext-pro", image=b, prompt="add a hat")

# after
litellm.image_edit(model="black_forest_labs/flux-kontext-pro", image=b, prompt="add a hat", api_key=os.environ["BFL_API_KEY"])

Defensive patterns

Strategy: validation

Validate before calling

import os

assert os.getenv("BFL_API_KEY") or os.getenv("BLACK_FOREST_LABS_API_KEY") or passed_api_key, \
    "BFL credentials missing — set BFL_API_KEY or pass api_key"

Type guard

null

Try / catch

from litellm.exceptions import AuthenticationError
try:
    litellm.image_edit(model=M, image=img, prompt=p)
except AuthenticationError:
    # surface a config action, not a retry
    raise RuntimeError("Configure BFL_API_KEY before using black_forest_labs models")

Prevention

Fail fast at startup: check BFL_API_KEY when your app boots if any BFL model is configured.
On the LiteLLM proxy, declare the env var in the config so missing keys fail at proxy startup, not per-request.
Never retry 401s — they are deterministic config errors.

When it happens

Trigger: Calling image_edit with a `black_forest_labs/*` model when: no api_key argument is passed AND neither BFL_API_KEY nor BLACK_FOREST_LABS_API_KEY is set in the environment of the LiteLLM process (or proxy server worker).

Common situations: Forgetting to export BFL_API_KEY in the shell; .env not loaded in the deployed environment; LiteLLM proxy config missing the `api_key`/environment_variables entry; CI runners lacking secrets; key set under a different name (e.g. BLACK_FOREST_LABS_KEY).

Related errors

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