What causes "Model needs to be set for black_forest_labs" in BerriAI/litellm?

Pass an explicit BFL model, e.g. model='black_forest_labs/flux-pro-1.0' or model='flux-dev' with custom_llm_provider='black_forest_labs'

BerriAI/litellm · error · Exception

Model needs to be set for black_forest_labs

Error message

Model needs to be set for black_forest_labs

What it means

The Black Forest Labs (FLUX) image route requires polling of an asynchronous job API, so litellm must know which BFL model to submit. At litellm/images/main.py:411, if custom_llm_provider=='black_forest_labs' and the resolved model is None, it raises this Exception because there is no default FLUX model to fall back to.

Source

Thrown at litellm/images/main.py:411

            _api_base: Final = api_base or litellm.api_base
            litellm_params_dict["api_base"] = _api_base

            return llm_http_handler.image_generation_handler(
                api_key=api_key,
                model=model,
                prompt=prompt,
                image_generation_provider_config=image_generation_config,
                image_generation_optional_request_params=optional_params,
                custom_llm_provider=custom_llm_provider,
                litellm_params=litellm_params_dict,
                logging_obj=litellm_logging_obj,
                timeout=timeout,
                client=client,
            )
        elif custom_llm_provider == "black_forest_labs":
            # Route to BFL-specific handler (polling required)
            if model is None:
                raise Exception("Model needs to be set for black_forest_labs")
            return bfl_image_generation.image_generation(
                model=model,
                prompt=prompt,
                model_response=model_response,
                optional_params=optional_params,
                litellm_params=litellm_params_dict,
                logging_obj=litellm_logging_obj,
                timeout=timeout,
                extra_headers=extra_headers,
                client=client,
                aimg_generation=aimg_generation,
            )
        elif custom_llm_provider == "azure_ai":
            from litellm.llms.azure_ai.common_utils import AzureFoundryModelInfo

            api_base = AzureFoundryModelInfo.get_api_base(api_base)
            api_key = AzureFoundryModelInfo.get_api_key(api_key)
            if extra_headers is not None:

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass an explicit BFL model, e.g. model='black_forest_labs/flux-pro-1.0' or model='flux-dev' with custom_llm_provider='black_forest_labs'
Verify the model string has a non-empty part after the provider prefix
Set the BFL API key (BFL_API_KEY or api_key=) so routing succeeds on retry

Example fix

# before
litellm.image_generation(prompt="a cat", custom_llm_provider="black_forest_labs")

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

Defensive patterns

Strategy: validation

Validate before calling

BFL_MODELS = {"flux-pro-1.0", "flux-dev", "flux-pro-1.1", "flux-kontext-pro"}

def validate_bfl_call(model: str | None) -> str:
    if model is None:
        raise ValueError("model is required for black_forest_labs image generation")
    bare = model.split("/", 1)[-1]
    assert bare in BFL_MODELS, f"unknown BFL model: {model}"
    return model

Type guard

def is_bfl_ready(model: str | None) -> bool:
    return model is not None and len(model.split('/', 1)[-1]) > 0

Try / catch

try:
    img = litellm.image_generation(model=m, prompt=p, custom_llm_provider="black_forest_labs")
except Exception as e:
    if "Model needs to be set" in str(e):
        # fail fast at call site with a clear message
        raise TypeError("BFL image generation requires an explicit model") from e
    raise

Prevention

Never call provider-specific image endpoints without an explicit model
Model required-parameters are cheap to check before the SDK call
Centralize model constants instead of passing user input straight through

When it happens

Trigger: Calling litellm.image_generation(prompt=..., custom_llm_provider='black_forest_labs') with no model argument; or passing a model string that get_llm_provider could not split into provider/model, leaving model=None; or setting model=None explicitly.

Common situations: Developer assumes a default image model exists (as with some OpenAI paths), passes only a prompt; or the model string was consumed into provider detection ('black_forest_labs/' with nothing after the slash).

Related errors

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