infiniflow/ragflow · error · ConnectorValidationError

Unexpected S3 client error (code={error_code}, status={statu

Error message

Unexpected S3 client error (code={error_code}, status={status_code}): {e}

What it means

The catch-all ConnectorValidationError raised by BlobStorageConnector.validate_connector_settings when the list_objects_v2 probe fails in a way that matches none of the mapped cases (credential errors, permission errors, missing bucket). It embeds the S3 error code, HTTP status, and the original exception text so the real cause stays diagnosable.

Source

Thrown at common/data_source/blob_connector.py:342

            status_code = getattr(e, "response", {}).get("ResponseMetadata", {}).get("HTTPStatusCode")

            # Common S3 error scenarios
            if error_code in [
                "AccessDenied",
                "InvalidAccessKeyId",
                "SignatureDoesNotMatch",
            ]:
                if status_code == 403 or error_code == "AccessDenied":
                    raise InsufficientPermissionsError(f"Insufficient permissions to list objects in bucket '{self.bucket_name}'. Please check your bucket policy and/or IAM policy.")
                if status_code == 401 or error_code == "SignatureDoesNotMatch":
                    raise CredentialExpiredError("Provided blob storage credentials appear invalid or expired.")

                raise CredentialExpiredError(f"Credential issue encountered ({error_code}).")

            if error_code == "NoSuchBucket" or status_code == 404:
                raise ConnectorValidationError(f"Bucket '{self.bucket_name}' does not exist or cannot be found.")

            raise ConnectorValidationError(f"Unexpected S3 client error (code={error_code}, status={status_code}): {e}")


if __name__ == "__main__":
    # Example usage
    credentials_dict = {
        "aws_access_key_id": os.environ.get("AWS_ACCESS_KEY_ID"),
        "aws_secret_access_key": os.environ.get("AWS_SECRET_ACCESS_KEY"),
    }

    # Initialize connector
    connector = BlobStorageConnector(
        bucket_type=os.environ.get("BUCKET_TYPE") or "s3",
        bucket_name=os.environ.get("BUCKET_NAME") or "yyboombucket",
        prefix="",
    )

    try:
        connector.load_credentials(credentials_dict)

View on GitHub (pinned to 554fb1133a)

Solutions

Read the embedded code/status and exception text — this branch is intentionally transparent; the fix depends on the underlying error
Test reachability of endpoint_url with curl -v (or the provider CLI) from the same host/network
For SlowDown/503, retry after a backoff — validation is a single MaxKeys=1 list, so sustained 503 means throttling or outage
Fix endpoint scheme/TLS config for S3-compatible stores (http vs https mismatch shows up here)

Defensive patterns

Strategy: retry

Validate before calling

import socket, urllib.parse
host = urllib.parse.urlparse(endpoint_url or 'https://s3.amazonaws.com').hostname
socket.getaddrinfo(host, 443)  # DNS check before running validation

Try / catch

from common.data_source.exceptions import ConnectorValidationError
for attempt in range(3):
    try:
        connector.validate_connector_settings()
        break
    except ConnectorValidationError as e:
        if 'SlowDown' in str(e) or '503' in str(e) or 'timeout' in str(e).lower():
            time.sleep(2 ** attempt)
            continue
        raise

Prevention

Read the embedded code/status in the message first — this branch is transparent by design and the fix depends on the underlying error
Keep the S3 endpoint reachable from the indexer (egress rules, proxy config) and verify TLS scheme correctness for S3-compatible stores

When it happens

Trigger: Network-level failures during the probe: DNS resolution errors, TLS certificate failures, connection timeouts, 5xx responses from S3 or the S3-compatible endpoint, throttling (SlowDown/503), VPC endpoint restrictions, or a misconfigured endpoint_url returning an HTML error page that boto3 surfaces oddly.

Common situations: Self-hosted MinIO down or restarting; endpoint_url scheme wrong (https against an http-only server); corporate proxy blocking the endpoint; S3 503 SlowDown under heavy listing; clock-skew-induced 403s that fall outside the mapped branches.

Related errors

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