BerriAI/litellm · error · BlackForestLabsError

No image URL in BFL result

Error message

No image URL in BFL result

What it means

The final BFL poll response parsed as JSON successfully, but `response_data["result"]["sample"]` was missing or falsy, so LiteLLM cannot build the OpenAI-compatible ImageResponse and raises BlackForestLabsError(500). The BFL contract expected here is `{"status": "Ready", "result": {"sample": "https://..."}}`; the poll loop only returns on status == "Ready", so this fires when a Ready payload lacks the sample URL (API contract change or unexpected payload shape).

Solutions

1. Upgrade LiteLLM to the latest release - BFL schema handling is maintained there (`pip install -U litellm`).
2. Dump the final poll response body (enable verbose logging or a custom logger) to see which field actually carries the image URL.
3. If using a custom/compatible gateway, align its Ready payload to `{"status": "Ready", "result": {"sample": "<url>"}}` or point at the official endpoint.
4. Retry once - a Ready-with-no-sample can be a transient upstream data issue.

from litellm.llms.black_forest_labs.common_utils import BlackForestLabsError

try:
    resp = litellm.image_edit(model="flux-kontext-pro", image=img, prompt=p)
except BlackForestLabsError as e:
    if "No image URL in BFL result" in str(e):
        log.error("BFL schema drift? raw status=%s", e.status_code)
        raise RuntimeError("provider returned no image URL") from e
    raise

When it happens

Trigger: BFL ships a payload where the image moved to a different field than `result.sample`; `result` present but `sample` null/empty (e.g. generation produced no output); a modified/custom base_url pointing at a BFL-compatible service that returns Ready with a different schema.

Common situations: Running an older LiteLLM against a newer BFL API after a response-format change; pointing `api_base`/base_url at a self-hosted BFL-compatible gateway whose schema differs; occasionally an upstream data issue where the task completes but no sample is attached.

Related errors

• Error parsing BFL response
• No polling_url in BFL response
• Error parsing initial response
• Max recursion depth reached while reading image bytes for…
• Unsupported image input: plain string values that are not…

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

Appendix: source

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

    ) -> 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}",
            )

        # Get image URL from result
        image_url: Final = response_data.get("result", {}).get("sample")
        if not image_url:
            raise BlackForestLabsError(
                status_code=500,
                message="No image URL in BFL result",
            )

        # Build ImageResponse
        return ImageResponse(
            created=int(time.time()),
            data=[ImageObject(url=image_url)],
        )

    def get_error_class(
        self, error_message: str, status_code: int, headers: dict | httpx.Headers
    ) -> BlackForestLabsError:
        """Return the appropriate error class for Black Forest Labs."""
        return BlackForestLabsError(
            status_code=status_code,
            message=error_message,
        )

View on GitHub (pinned to 77b7c6c40c)