run-llama/llama_index · error · ValueError

At least one error to retry needs to be provided

Error message

At least one error to retry needs to be provided

What it means

The retry_decorator-style helper in llama_index.core.utils (used to retry LLM calls on transient errors) requires a non-empty errors_to_retry list; with nothing to match it cannot decide what to retry, so it raises ValueError immediately. ErrorToRetry entries pair an exception class with an optional check_fn that inspects the exception instance.

Source

Thrown at llama-index-core/llama_index/core/utils.py:261

    min_backoff_secs: float = 0.5,
    max_backoff_secs: float = 60.0,
) -> Any:
    """
    Execute lambda function with retries and exponential backoff.

    Args:
        lambda_fn (Callable): Function to be called and output we want.
        errors_to_retry (List[ErrorToRetry]): List of errors to retry.
            At least one needs to be provided.
        max_tries (int): Maximum number of tries, including the first. Defaults to 10.
        min_backoff_secs (float): Minimum amount of backoff time between attempts.
            Defaults to 0.5.
        max_backoff_secs (float): Maximum amount of backoff time between attempts.
            Defaults to 60.

    """
    if not errors_to_retry:
        raise ValueError("At least one error to retry needs to be provided")

    error_checks = {
        error_to_retry.exception_cls: error_to_retry.check_fn
        for error_to_retry in errors_to_retry
    }
    exception_class_tuples = tuple(error_checks.keys())

    backoff_secs = min_backoff_secs
    tries = 0

    while True:
        try:
            return lambda_fn()
        except exception_class_tuples as e:
            traceback.print_exc()
            tries += 1
            if tries >= max_tries:
                raise

View on GitHub (pinned to afd0fef371)

Solutions

1. Provide at least one entry: errors_to_retry=[ErrorToRetry(exception_cls=RateLimitError)].
2. If config may legitimately have none, skip applying the decorator when the list is empty.
3. For OpenAI-style APIs, the common retry set is RateLimitError, APIConnectionError, APITimeoutError.

Example fix

# before
 fn = retry_decorator(
     lambda_fn=call_llm,
     errors_to_retry=[],  # -> ValueError
 )(call_llm)

# after
from openai import APIConnectionError, RateLimitError
from llama_index.core.utils import ErrorToRetry

 fn = retry_decorator(
     lambda_fn=call_llm,
     errors_to_retry=[
         ErrorToRetry(exception_cls=RateLimitError),
         ErrorToRetry(exception_cls=APIConnectionError),
     ],
 )(call_llm)

DEFAULT_RETRY_ERRORS = (
    ErrorToRetry(exception_cls=RateLimitError),
    ErrorToRetry(exception_cls=APIConnectionError),
)

def retry_errors_or_default(errors):
    return errors or list(DEFAULT_RETRY_ERRORS)

def is_valid_errors_to_retry(errors) -> bool:
    return bool(errors) and all(
        hasattr(e, 'exception_cls') and isinstance(e.exception_cls, type)
        and issubclass(e.exception_cls, BaseException)
        for e in errors
    )

try:
    fn = retry_decorator(lambda_fn=call, errors_to_retry=errors)(call)
except ValueError as e:
    if 'error to retry' in str(e):
        fn = retry_decorator(lambda_fn=call, errors_to_retry=list(DEFAULT_RETRY_ERRORS))(call)
    else:
        raise

When it happens

Trigger: Calling the decorated function (or constructing via the helper) with errors_to_retry=[] or errors_to_retry=None - typically when the list is built dynamically from config and ends up empty, or a default argument was overridden.

Common situations: Config-driven retry setups where the error classes list comes from YAML and is missing/empty; refactors that moved the defaults but left the parameter mandatory; passing tuples/strings instead of ErrorToRetry instances.

Related errors

• Multimodal synthesis requires a chat LLM.
• Got empty streaming response
• Expected ActionReasoningStep, got {reasoning_step}
• LLM only supports text inputs
• Invalid message content: {message.content!s}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/4a457670ecb7e7ec. Report an issue: GitHub.