infiniflow/ragflow · error · RuntimeError

Failed to load Jira documents: {failure_message}

Error message

Failed to load Jira documents: {failure_message}

What it means

A RuntimeError raised inside the streaming test utility (yield_jira_documents-style helper at connector.py:873) when the underlying connector load yields a ConnectorFailure instead of a Document. The helper deliberately converts structured per-document failures into a hard error, embedding failure.failure_message, because a test run should not silently skip documents.

Source

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

def iterate_jira_documents(
    connector: "JiraConnector",
    start: SecondsSinceUnixEpoch,
    end: SecondsSinceUnixEpoch,
    iteration_limit: int = 100_000,
) -> Iterator[Document]:
    """Yield documents without materializing the entire result set."""

    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,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Read the embedded failure_message — it names the exact item and reason (e.g. 'Jira issue X returned 403') that caused the ConnectorFailure.
2. Fix the underlying cause: grant the token browse access, add labels_to_skip for problem issues, or raise attachment_size_limit handling.
3. If running a smoke test rather than exhaustive verification, narrow jql_query/project_key to a slice of issues you know are accessible.
4. For resilient production loading, use the standard checkpointed load path (which surfaces ConnectorFailure objects for handling) instead of this all-or-nothing test helper.

Example fix

# before
docs = list(yield_jira_documents(connector, start, end))  # RuntimeError: Failed to load Jira documents: <failure_message>

# after
from common.utils.retry_wrapper import ...  # use the standard load path instead
for document, failure, next_checkpoint in CheckpointOutputWrapper[JiraCheckpoint]()(connector.load_from_checkpoint(start=start, end=end, checkpoint=checkpoint)):
    if failure is not None:
        logger.warning("skipping failed item: %s", failure.failure_message)
        continue
    process(document)

try:
    docs = list(yield_jira_documents(connector, start, end))
except RuntimeError as exc:
    if not str(exc).startswith("Failed to load Jira documents"):
        raise
    handle_connector_failure(str(exc))  # message embeds failure.failure_message

When it happens

Trigger: Running the CLI/test path that drives load_from_checkpoint through CheckpointOutputWrapper; any single issue, comment fetch, or attachment download inside the Jira connector returning a ConnectorFailure (e.g. a 403 on one issue, an oversized attachment, a transient 429 handled as failure) aborts the whole stream with this RuntimeError.

Common situations: Ad-hoc ingestion tests against a project containing restricted issues the token cannot read; token lacking browse permission for some issues; flaky network during a test run; one malformed issue record converted into a ConnectorFailure by the connector's per-item error handling.

Related errors

• Too many iterations while loading Jira documents.
• Database error (File doesn't exist)!
• Airtable credentials not loaded
• Azure Blob: failed to download {name}: {exc}
• Azure Blob listing failed: {exc}

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