BerriAI/litellm · error · BlackForestLabsError

Image generation failed

Error message

Image generation failed: {status}

What it means

Sync BFL polling: the task reached a terminal non-success status - one of `Error`, `Failed`, `Content Moderated`, `Request Moderated` - and LiteLLM maps it to BlackForestLabsError(status_code=400) with the status string in the message. The BFL job itself finished badly; retrying the identical request will often fail the same way, except for transient `Error`/`Failed`.

Solutions

1. If status is 'Content Moderated'/'Request Moderated': rephrase the prompt or swap the input image - this is policy, not a bug; consider surfacing a user-facing moderation message.
2. If status is 'Error'/'Failed': retry once or twice (transient worker failures happen), then inspect the input image (re-encode to standard RGB PNG/JPEG) if it persists.
3. Route moderated cases to a different model or provider if the use case is legitimately benign.
4. Track which prompts trigger moderation so you can pre-filter instead of burning BFL credits.

from litellm.llms.black_forest_labs.common_utils import BlackForestLabsError

try:
    resp = litellm.image_generation(model="flux-pro-1.1", prompt=p)
except BlackForestLabsError as e:
    msg = str(e)
    if "Moderated" in msg:
        return moderation_feedback_to_user()      # do not blind-retry
    if "Image generation failed" in msg:
        return retry_with_backoff(...)            # Error/Failed may be transient
    raise

When it happens

Trigger: Prompt or input image violating BFL content policy (`Content Moderated` / `Request Moderated` - text or the uploaded image tripped filters); upstream BFL worker failure (`Error`/`Failed`) from malformed media, unsupported image characteristics, or infra crashes.

Common situations: User-generated prompts in an app hitting safety filters; NSFW-adjacent or violent wording even in legitimate contexts (medical, gaming); corrupt or unusual input images (CMYK JPEG, exotic formats) causing Failed; occasional platform-wide Error bursts.

Related errors

• Error parsing initial response
• Polling failed
• Polling timed out after
• Request failed
• BFL error

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

Appendix: source

Thrown at litellm/llms/black_forest_labs/image_generation/handler.py:366

                raise BlackForestLabsError(
                    status_code=response.status_code,
                    message=f"Polling failed: {response.text}",
                )

            data = response.json()
            status = data.get("status")

            verbose_logger.debug("BFL poll status: %s", status)

            if status == "Ready":
                return response
            elif status in [
                "Error",
                "Failed",
                "Content Moderated",
                "Request Moderated",
            ]:
                raise BlackForestLabsError(
                    status_code=400,
                    message=f"Image generation failed: {status}",
                )

            time.sleep(interval)

        raise BlackForestLabsError(
            status_code=408,
            message=f"Polling timed out after {max_wait} seconds",
        )

    async def _poll_for_result_async(
        self,
        initial_response: httpx.Response,
        headers: dict,
        async_client: AsyncHTTPHandler,
        max_wait: float = DEFAULT_MAX_POLLING_TIME,
        interval: float = DEFAULT_POLLING_INTERVAL,

View on GitHub (pinned to 77b7c6c40c)