BerriAI/litellm · error · HuggingFaceError

reranker requires 2+ sentences

Error message

reranker requires 2+ sentences

What it means

When the resolved pipeline tag is 'rerank' (or task_type='rerank' is passed), the HF embedding handler reshapes input into {'query': input[0], 'texts': input[1:]} — the TEI rerank payload. With fewer than two inputs there is nothing to rank against the query, so HuggingFaceError(400) 'reranker requires 2+ sentences' is raised client-side before any request.

Solutions

1. Pass query plus candidates in one input list: input=[query, doc1, doc2, ...]
2. For real reranking workflows prefer litellm.rerank with a supported rerank provider/model
3. For plain embeddings use an embedding model (feature-extraction/embed pipeline tag) instead of a reranker
4. Guard input length before calling when lists are built dynamically

Example fix

# before
litellm.embedding(model="hf/BAAI/bge-reranker-base", input=["what is litellm?"])

# after
litellm.embedding(
    model="hf/BAAI/bge-reranker-base",
    input=["what is litellm?", "a proxy for 100+ LLMs"],
)

def ok_for_rerank_model(input_list: list[str], pipeline_tag: str) -> bool:
    if pipeline_tag == "rerank":
        return len(input_list) >= 2
    return True

assert ok_for_rerank_model(input, "rerank"), "need query + at least one candidate text"

def is_valid_hf_embedding_input(inputs: list, pipeline_tag: str | None) -> bool:
    if pipeline_tag is None:
        return True
    if pipeline_tag in ("sentence-similarity", "similarity", "rerank"):
        return len(inputs) >= 2
    return True

When it happens

Trigger: litellm.embedding(model='hf/<cross-encoder-reranker>', input=['single string']) where the model's pipeline_tag is rerank; passing task_type='rerank' with a one-element input list to any HF model.

Common situations: Pointing litellm.embedding at a cross-encoder/reranker model; batch pipelines whose candidate list was filtered down to one item; misunderstanding that reranking via this route requires query plus at least one candidate as one call.

Related errors

• sentence-similarity requires 2+ sentences
• Bedrock batch embedding `input` must be a string (or a…
• {error_str}
• Invalid task_type= . Expected one of=
• api_base is required for hosted_vllm embeddings

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

Appendix: source

Thrown at litellm/llms/huggingface/embedding/handler.py:87

    _client_session: httpx.Client | None = None
    _aclient_session: httpx.AsyncClient | None = None

    def __init__(self) -> None:
        super().__init__()

    def _transform_input_on_pipeline_tag(self, input: list, pipeline_tag: str | None) -> dict:
        if pipeline_tag is None:
            return {"inputs": input}
        if pipeline_tag == "sentence-similarity" or pipeline_tag == "similarity":
            if len(input) < 2:
                raise HuggingFaceError(
                    status_code=400,
                    message="sentence-similarity requires 2+ sentences",
                )
            return {"inputs": {"source_sentence": input[0], "sentences": input[1:]}}
        elif pipeline_tag == "rerank":
            if len(input) < 2:
                raise HuggingFaceError(
                    status_code=400,
                    message="reranker requires 2+ sentences",
                )
            return {"inputs": {"query": input[0], "texts": input[1:]}}
        return {"inputs": input}  # default to feature-extraction pipeline tag

    async def _async_transform_input(
        self,
        model: str,
        task_type: str | None,
        embed_url: str,
        input: list,
        optional_params: dict,
    ) -> dict:
        hf_task = await async_get_hf_task_embedding_for_model(model=model, task_type=task_type, api_base=HF_HUB_URL)

        data: Final = self._transform_input_on_pipeline_tag(input=input, pipeline_tag=hf_task)

View on GitHub (pinned to 77b7c6c40c)