BerriAI/litellm · error · BlackForestLabsError

Error parsing BFL response: {e}

Error message

Error parsing BFL response: {e}

What it means

transform_response calls raw_response.json() on the final polled BFL response (the one with status 'Ready'). If the body is not valid JSON — HTML error page, empty body, truncated payload — the exception is caught and re-raised as BlackForestLabsError carrying the HTTP status code and the parser error text. It indicates the response transport/shape is broken, not that generation failed.

Source

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

        model_response: ImageResponse,
        logging_obj: LiteLLMLoggingObj,
        request_data: dict,
        optional_params: dict,
        litellm_params: dict,
        encoding: Any,
        api_key: str | None = None,
        json_mode: bool | None = None,
    ) -> ImageResponse:
        """
        Transform Black Forest Labs response to OpenAI-compatible ImageResponse.

        This is called with the FINAL polled response (after handler does polling).
        The response contains: {"status": "Ready", "result": {"sample": "https://..."}}
        """
        try:
            response_data: Final = raw_response.json()
        except Exception as e:
            raise BlackForestLabsError(
                status_code=raw_response.status_code,
                message=f"Error parsing BFL response: {e}",
            )

        result: Final = response_data.get("result", {})

        if not model_response.data:
            model_response.data = []

        # Handle single image (sample) or multiple images
        if isinstance(result, dict) and "sample" in result:
            model_response.data.append(ImageObject(url=result["sample"]))
        elif isinstance(result, list):
            # Multiple images returned
            for img in result:
                if isinstance(img, str):
                    model_response.data.append(ImageObject(url=img))
                elif isinstance(img, dict) and "url" in img:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Inspect the exception's embedded parser message and, if possible, log raw_response.text[:500] to see the actual body.
2. Retry the request — transient gateway corruption is the most common cause.
3. If a proxy sits in front, bypass or fix it (buffering/timeout/rewrite rules).
4. Check BFL status during incidents; open a litellm issue if the body is JSON but a schema change broke parsing.

try:
    resp = client.transform_response(...)  # or images.generate
except BlackForestLabsError as e:
    if "Error parsing BFL response" in str(e):
        logger.warning("BFL returned unparseable body (status %s); retrying", e.status_code)
        return retry_with_backoff()
    raise

When it happens

Trigger: The polling endpoint returns 200 but a non-JSON body (HTML maintenance page, empty string), or a proxy/CDN truncates or rewrites the JSON; json.JSONDecodeError (or any parsing exception) is raised inside the try block.

Common situations: BFL gateway serving an HTML 200 error page during incidents; response body gzip/encoding corruption via middleboxes; mock/test servers returning plain text; very large result payloads cut off by proxy buffering limits.

Related errors

• Error parsing BFL response: {e}
• Error parsing initial response: {e}
• Error in response object format, got None
• Invalid JSON response: {raw_response.text}
• Failed to parse OCI embed response as JSON: {e}

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