{"record":{"id":"0313df5fc1e70f90","repo":"infiniflow/ragflow","slug":"azure-blob-listing-failed-exc","errorCode":null,"errorMessage":"Azure Blob listing failed: {exc}","messagePattern":"Azure Blob listing failed: (.+?)","errorType":"validation","errorClass":"UnexpectedValidationError","httpStatus":null,"severity":"error","filePath":"common/data_source/azure_blob_connector.py","lineNumber":357,"sourceCode":"                    blob=data,\n                    doc_updated_at=doc_updated_at,\n                    size_bytes=len(data),\n                    fingerprint=current_etag or None,\n                    metadata={\n                        \"container\": _container_name(self._container_client),\n                        \"etag\": current_etag,\n                        \"prefix\": self.prefix,\n                    },\n                )\n                batch.append(doc)\n\n                if len(batch) >= self.batch_size:\n                    yield batch\n                    batch = []\n        except UnexpectedValidationError:\n            raise\n        except Exception as exc:\n            raise UnexpectedValidationError(f\"Azure Blob listing failed: {exc}\") from exc\n\n        if batch:\n            yield batch\n\n        if checkpoint is not None:\n            checkpoint.has_more = False\n\n\n# ----------------------------------------------------------------------\n# Module-level helpers\n# ----------------------------------------------------------------------\n\n\ndef _extension(name: str) -> str:\n    if \".\" not in name:\n        return \"\"\n    return \".\" + name.rsplit(\".\", 1)[-1].lower()\n","sourceCodeStart":339,"sourceCodeEnd":375,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/azure_blob_connector.py#L339-L375","documentation":"Catch-all at the end of _iter_documents: any exception during the listing/processing loop that is not already an UnexpectedValidationError (those are re-raised verbatim by 'except UnexpectedValidationError: raise') gets wrapped as UnexpectedValidationError. It covers list_blobs() pager failures and unexpected bugs in the per-blob processing inside the loop.","triggerScenarios":"Running document iteration where list_blobs() itself throws (auth expiry, network), or non-download processing code inside the loop raises something other than the wrapped download error — e.g. datetime/ETag handling bugs. Deliberate per-blob download failures (531) pass through unchanged.","commonSituations":"SAS token expiring during a long first ingestion of a large container, network interruptions, or SDK version changes altering blob property types used in the loop (e.g. last_modified None handling).","solutions":["Read exc.__cause__ to identify whether the failure is the pager (auth/network) or loop logic","For auth expiry: use longer-lived credentials or account-key auth for initial full syncs","Retry the run; checkpointing prevents duplicate or missed batches on restart","If the cause points at loop logic (TypeError/AttributeError on blob_props), file/patch the connector rather than retrying"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"# Nothing local predicts pager failure; mitigate by sizing credentials:\nif mode == \"sas_token\" and estimated_blobs(container) > 100_000:\n    assert sas_lifetime_hours(sas_token) > 4, \"use account-key auth for large initial syncs\"","typeGuard":null,"tryCatchPattern":"try:\n    for batch in connector.load_from_checkpoint(start, end, checkpoint):\n        process(batch)\nexcept UnexpectedValidationError as e:\n    cause = e.__cause__\n    if is_transient_network_error(cause):\n        retry_run_with_backoff()  # checkpoint makes restart safe\n    else:\n        raise","preventionTips":["Use long-lived credentials for the initial full sync of big containers","Keep ingestion jobs restartable: checkpoints make retry the correct default response","Separate transient (network/auth-expiry) from permanent (TypeError in loop) causes via __cause__ before choosing retry vs bug report"],"tags":["azure","azure-blob","listing","transient","ingestion"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}