microsoft/graphrag · error · ValueError

max_retries must be greater than 1 for Exponential Backoff r

Error message

max_retries must be greater than 1 for Exponential Backoff retry.

What it means

RetryConfig validation requires max_retries > 1 for Exponential Backoff retry. A single retry makes backoff pointless, so values of 1 or less are rejected at config load.

Source

Thrown at packages/graphrag-llm/graphrag_llm/config/retry_config.py:46

        default=None,
        description="The base delay in seconds for exponential backoff.",
    )

    jitter: bool | None = Field(
        default=None,
        description="Whether to apply jitter to the delay intervals in exponential backoff.",
    )

    max_delay: float | None = Field(
        default=None,
        description="The maximum delay in seconds between retries.",
    )

    def _validate_exponential_backoff_config(self) -> None:
        """Validate Exponential Backoff retry configuration."""
        if self.max_retries is not None and self.max_retries <= 1:
            msg = "max_retries must be greater than 1 for Exponential Backoff retry."
            raise ValueError(msg)

        if self.base_delay is not None and self.base_delay <= 1.0:
            msg = "base_delay must be greater than 1.0 for Exponential Backoff retry."
            raise ValueError(msg)

        if self.max_delay is not None and self.max_delay <= 1:
            msg = "max_delay must be greater than 1 for Exponential Backoff retry."
            raise ValueError(msg)

    def _validate_immediate_config(self) -> None:
        """Validate Immediate retry configuration."""
        if self.max_retries is not None and self.max_retries <= 1:
            msg = "max_retries must be greater than 1 for Immediate retry."
            raise ValueError(msg)

    @model_validator(mode="after")
    def _validate_model(self):
        """Validate the retry configuration based on its type."""

View on GitHub (pinned to f40e9a26ce)

Solutions

Set max_retries to 2 or higher (e.g. 3) for exponential backoff
If you truly want a single immediate retry, reconsider: the validator requires >1 for all types, so use max_retries=2 or disable retries

Example fix

# before
RetryConfig(type="exponential_backoff", max_retries=1)
# after
RetryConfig(type="exponential_backoff", max_retries=3)

Defensive patterns

Strategy: validation

Validate before calling

mr = retry_cfg.get("max_retries")
if retry_cfg.get("type") == "exponential_backoff" and mr is not None and mr <= 1:
    raise ValueError("max_retries must be > 1")

Prevention

Use sensible defaults (max_retries=3) in config templates
Never hand-tune retries below 2; disable retry config instead

When it happens

Trigger: RetryConfig(type=RetryType.ExponentialBackoff, max_retries=1) (or 0/negative) in code or settings.yaml.

Common situations: Copying a config tuned for Immediate retry (where 1 is also invalid) into an exponential block; trimming retries to 'just one more try' during debugging.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of microsoft/graphrag@f40e9a26ce (2026-08-27). Data as JSON: /api/errors/10b410fc7325dad4. Report an issue: GitHub.