BerriAI/litellm · error · HuggingFaceError

reranker requires 2+ sentences

Error message

reranker requires 2+ sentences

What it means

Raised by the HuggingFace embedding handler when the pipeline tag is 'rerank' and the input list has fewer than 2 entries. The rerank endpoint needs a query (input[0]) plus at least one document to score (input[1:]), so litellm fails fast with HTTP 400.

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 6c2dcb801b)

Solutions

1. Pass input=[query, doc1, doc2, ...] so there is at least one document to rerank.
2. If you want embeddings rather than reranking, switch to a feature-extraction model.
3. If you want reranking, prefer litellm.rerank() with the huggingface provider, which maps query/documents correctly.

Example fix

# before
input_list = [query]  # documents list was empty
litellm.embedding(model='huggingface/BAAI/bge-reranker-base', input=input_list)

# after
input_list = [query] + documents
litellm.rerank(model='huggingface/BAAI/bge-reranker-base', query=query, documents=documents)

def validate_rerank_input(input_list: list[str]) -> bool:
    # query + at least one document
    return len(input_list) >= 2 and bool(input_list[1])

try:
    litellm.embedding(model=model, input=texts)
except litellm.llms.huggingface.common_utils.HuggingFaceError as e:
    if 'reranker requires' in str(e):
        logger.warning('reranker model used via embedding API; falling back to empty scores')
        return []
    raise

When it happens

Trigger: Calling the embedding endpoint on a model whose HF pipeline tag is 'rerank' (e.g. BAAI/bge-reranker-base) with input=['query'] or input=[]; the request is rejected before any HTTP call is made.

Common situations: Developer points an embedding integration at a reranker model by mistake, or sends only the query because the documents list was empty after upstream filtering.

Related errors

• sentence-similarity requires 2+ sentences
• query is required for HuggingFace rerank
• Cohere 'documents' param is required for HuggingFace rerank
• model is required
• No results found in the response={response}

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