{"record":{"id":"c30962e583489abf","repo":"infiniflow/ragflow","slug":"failed-to-load-jira-documents-failure-message","errorCode":null,"errorMessage":"Failed to load Jira documents: {failure_message}","messagePattern":"Failed to load Jira documents: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"common/data_source/jira/connector.py","lineNumber":873,"sourceCode":"def iterate_jira_documents(\n    connector: \"JiraConnector\",\n    start: SecondsSinceUnixEpoch,\n    end: SecondsSinceUnixEpoch,\n    iteration_limit: int = 100_000,\n) -> Iterator[Document]:\n    \"\"\"Yield documents without materializing the entire result set.\"\"\"\n\n    checkpoint = connector.build_dummy_checkpoint()\n    iterations = 0\n\n    while checkpoint.has_more:\n        wrapper = CheckpointOutputWrapper[JiraCheckpoint]()\n        generator = wrapper(connector.load_from_checkpoint(start=start, end=end, checkpoint=checkpoint))\n\n        for document, failure, next_checkpoint in generator:\n            if failure is not None:\n                failure_message = getattr(failure, \"failure_message\", str(failure))\n                raise RuntimeError(f\"Failed to load Jira documents: {failure_message}\")\n            if document is not None:\n                yield document\n            if next_checkpoint is not None:\n                checkpoint = next_checkpoint\n\n        iterations += 1\n        if iterations > iteration_limit:\n            raise RuntimeError(\"Too many iterations while loading Jira documents.\")\n\n\ndef test_jira(\n    *,\n    base_url: str,\n    project_key: str | None = None,\n    jql_query: str | None = None,\n    credentials: dict[str, Any],\n    batch_size: int = INDEX_BATCH_SIZE,\n    start_ts: float | None = None,","sourceCodeStart":855,"sourceCodeEnd":891,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/jira/connector.py#L855-L891","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the embedded failure_message — it names the exact item and reason (e.g. 'Jira issue X returned 403') that caused the ConnectorFailure.","Fix the underlying cause: grant the token browse access, add labels_to_skip for problem issues, or raise attachment_size_limit handling.","If running a smoke test rather than exhaustive verification, narrow jql_query/project_key to a slice of issues you know are accessible.","For resilient production loading, use the standard checkpointed load path (which surfaces ConnectorFailure objects for handling) instead of this all-or-nothing test helper."],"exampleFix":"# before\ndocs = list(yield_jira_documents(connector, start, end))  # RuntimeError: Failed to load Jira documents: <failure_message>\n\n# after\nfrom common.utils.retry_wrapper import ...  # use the standard load path instead\nfor document, failure, next_checkpoint in CheckpointOutputWrapper[JiraCheckpoint]()(connector.load_from_checkpoint(start=start, end=end, checkpoint=checkpoint)):\n    if failure is not None:\n        logger.warning(\"skipping failed item: %s\", failure.failure_message)\n        continue\n    process(document)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    docs = list(yield_jira_documents(connector, start, end))\nexcept RuntimeError as exc:\n    if not str(exc).startswith(\"Failed to load Jira documents\"):\n        raise\n    handle_connector_failure(str(exc))  # message embeds failure.failure_message","preventionTips":["Prefer the standard checkpointed load path in production; this helper is for exhaustive test runs.","Narrow jql_query to accessible issues before smoke tests.","Log the embedded failure_message verbatim — it identifies the exact failing item."],"tags":["jira","testing","ingestion","connector-failure","runtime-error"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}