infiniflow/ragflow · error · UnexpectedValidationError

Azure Blob listing failed: {exc}

Error message

Azure Blob listing failed: {exc}

What it means

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.

Source

Thrown at common/data_source/azure_blob_connector.py:357

                    blob=data,
                    doc_updated_at=doc_updated_at,
                    size_bytes=len(data),
                    fingerprint=current_etag or None,
                    metadata={
                        "container": _container_name(self._container_client),
                        "etag": current_etag,
                        "prefix": self.prefix,
                    },
                )
                batch.append(doc)

                if len(batch) >= self.batch_size:
                    yield batch
                    batch = []
        except UnexpectedValidationError:
            raise
        except Exception as exc:
            raise UnexpectedValidationError(f"Azure Blob listing failed: {exc}") from exc

        if batch:
            yield batch

        if checkpoint is not None:
            checkpoint.has_more = False


# ----------------------------------------------------------------------
# Module-level helpers
# ----------------------------------------------------------------------


def _extension(name: str) -> str:
    if "." not in name:
        return ""
    return "." + name.rsplit(".", 1)[-1].lower()

View on GitHub (pinned to 554fb1133a)

Solutions

1. Read exc.__cause__ to identify whether the failure is the pager (auth/network) or loop logic
2. For auth expiry: use longer-lived credentials or account-key auth for initial full syncs
3. Retry the run; checkpointing prevents duplicate or missed batches on restart
4. If the cause points at loop logic (TypeError/AttributeError on blob_props), file/patch the connector rather than retrying

# Nothing local predicts pager failure; mitigate by sizing credentials:
if mode == "sas_token" and estimated_blobs(container) > 100_000:
    assert sas_lifetime_hours(sas_token) > 4, "use account-key auth for large initial syncs"

try:
    for batch in connector.load_from_checkpoint(start, end, checkpoint):
        process(batch)
except UnexpectedValidationError as e:
    cause = e.__cause__
    if is_transient_network_error(cause):
        retry_run_with_backoff()  # checkpoint makes restart safe
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Azure Blob prune listing failed: {exc}
• Azure Blob: failed to download {name}: {exc}
• Azure Blob: container_name is required together with account
• Azure Blob: container_url and sas_token are required for the
• Azure Blob credentials are incomplete. Provide one of: (a) c

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