BerriAI/litellm · error · HuggingFaceError

Original Response received: {raw_response.text}

Error message

Original Response received: {raw_response.text}

What it means

Raised when raw_response.json() throws — the HuggingFace completion endpoint returned a body that is not valid JSON (commonly an HTML error page, plain-text 502/503 from a proxy, or an empty body). The full raw body is embedded in the message so you can see what actually came back.

Source

Thrown at litellm/llms/huggingface/embedding/transformation.py:505

                model=model,
                data=request_data,
                api_key=api_key,
            )
        else:
            ## LOGGING
            logging_obj.post_call(
                input=request_data,
                api_key=api_key,
                original_response=raw_response.text,
                additional_args={"complete_input_dict": request_data},
            )
            ## RESPONSE OBJECT
            try:
                completion_response = raw_response.json()
                if isinstance(completion_response, dict):
                    completion_response = [completion_response]
            except Exception:
                raise HuggingFaceError(
                    message=f"Original Response received: {raw_response.text}",
                    status_code=raw_response.status_code,
                )

        if isinstance(completion_response, dict) and "error" in completion_response:
            raise HuggingFaceError(
                message=completion_response["error"],
                status_code=raw_response.status_code,
            )
        return self.convert_to_model_response_object(
            completion_response=completion_response,
            model_response=model_response,
            task=task if task is not None and task in hf_task_list else None,
            optional_params=optional_params,
            encoding=encoding,
            messages=messages,
            model=model,
        )

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Read the embedded raw_response.text — HTML titles like '502 Bad Gateway' reveal the true source.
2. Fix api_base to point at the inference route (e.g. ends with the model path, not the web UI).
3. Retry with backoff for transient gateway errors.
4. Verify the endpoint with curl -v to confirm it serves JSON.

try:
    resp = litellm.completion(...)
except litellm.llms.huggingface.common_utils.HuggingFaceError as e:
    if '<html' in str(e).lower() or 'bad gateway' in str(e).lower():
        logger.warning('gateway error from HF endpoint; retrying later')
        raise TransientUpstreamError(str(e)) from e
    raise

When it happens

Trigger: HF inference endpoint behind a gateway returning HTML 502/504, a Cloudflare block page, an empty 500 response, or a mis-typed api_base that hits a non-JSON route.

Common situations: Self-hosted endpoints where the URL path is wrong (hits the UI page), transient infra errors, or corporate proxies replacing bodies with HTML.

Related errors

• {raw_response.text}
• response is not in expected format - {completion_response}
• Invalid hf task - {task}. Valid formats - {hf_tasks}.
• {completion_response[error]}
• {raw_response.text}

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