infiniflow/ragflow · error · RuntimeError

Too many iterations while loading Jira documents.

Error message

Too many iterations while loading Jira documents.

What it means

A RuntimeError raised by the test load helper when the pagination loop exceeds iteration_limit full passes without the checkpoint reaching has_more=False. It is an infinite-loop safeguard: each outer iteration should advance the Jira checkpoint (start_at offset / paginated cursor), and if it never terminates the helper assumes checkpoint advancement is broken.

Source

Thrown at common/data_source/jira/connector.py:881

    checkpoint = connector.build_dummy_checkpoint()
    iterations = 0

    while checkpoint.has_more:
        wrapper = CheckpointOutputWrapper[JiraCheckpoint]()
        generator = wrapper(connector.load_from_checkpoint(start=start, end=end, checkpoint=checkpoint))

        for document, failure, next_checkpoint in generator:
            if failure is not None:
                failure_message = getattr(failure, "failure_message", str(failure))
                raise RuntimeError(f"Failed to load Jira documents: {failure_message}")
            if document is not None:
                yield document
            if next_checkpoint is not None:
                checkpoint = next_checkpoint

        iterations += 1
        if iterations > iteration_limit:
            raise RuntimeError("Too many iterations while loading Jira documents.")


def test_jira(
    *,
    base_url: str,
    project_key: str | None = None,
    jql_query: str | None = None,
    credentials: dict[str, Any],
    batch_size: int = INDEX_BATCH_SIZE,
    start_ts: float | None = None,
    end_ts: float | None = None,
    connector_options: dict[str, Any] | None = None,
) -> list[Document]:
    """Programmatic entry point that mirrors the CLI workflow."""

    connector_kwargs = connector_options.copy() if connector_options else {}
    connector = JiraConnector(
        jira_base_url=base_url,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Check whether iteration_limit is simply too small for the dataset — the limit counts outer checkpoint passes, so raise it for large projects.
2. Log checkpoint.start_at and has_more per iteration to confirm the offset actually advances; if frozen, inspect the connector's pagination logic and the checkpoint model fields.
3. If next_checkpoint is never yielded by the generator, fix that path — the helper only advances when next_checkpoint is not None.
4. For test stubs, make the fake client return has_more=False on the final page.

Example fix

# before
docs = list(yield_jira_documents(connector, start, end))  # RuntimeError: Too many iterations

# after
# small dataset but default iteration_limit too low / or checkpoint frozen — debug first
from copy import deepcopy
cp = connector.build_dummy_checkpoint()
passes = 0
while cp.has_more:
    for doc, failure, ncp in CheckpointOutputWrapper[JiraCheckpoint]()(connector.load_from_checkpoint(start=start, end=end, checkpoint=cp)):
        ...
        if ncp is not None:
            cp = ncp
    passes += 1
    print(passes, cp.start_at, cp.has_more)  # verify offset advances

cp = connector.build_dummy_checkpoint()
assert cp.has_more is not None  # checkpoint model intact before long runs

try:
    docs = list(yield_jira_documents(connector, start, end))
except RuntimeError as exc:
    if str(exc) != "Too many iterations while loading Jira documents.":
        raise
    # dump checkpoint state and raise a diagnostic

When it happens

Trigger: Driving load_from_checkpoint in the helper's while-loop where each pass returns a checkpoint whose has_more stays True forever — e.g. the Jira search returning the same page because start_at is not incremented, next_checkpoint never being yielded (so `checkpoint` is never replaced), or a checkpoint round-trip (model_validate_json) losing the offset.

Common situations: Checkpoint serialization bug after a model change dropping start_at; a mocked/stubbed jira_client in tests that always returns the same page; Jira server ignoring the startAt parameter; passing iteration_limit too low for very large projects (each outer loop = one checkpoint batch, not one page).

Related errors

• Failed to load Jira documents: {failure_message}
• page_size must be less than or equal to {REST_API_MAX_PAGE_S
• {field_name} must contain at most {REST_API_MAX_IDS} IDs
• GitHub
• Jira base URL must be provided.

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/882eeb6856a9d432. Report an issue: GitHub.