infiniflow/ragflow · error · ConnectorValidationError

Bucket '{self.bucket_name}' does not exist or cannot be foun

Error message

Bucket '{self.bucket_name}' does not exist or cannot be found.

What it means

Raised by BlobStorageConnector.validate_connector_settings when the list_objects_v2 probe fails with S3 error code NoSuchBucket or any 404 status. This means authentication succeeded and permissions are likely fine, but the bucket named in the connector config does not exist (or is not visible to this account). Reported as ConnectorValidationError, a configuration problem rather than a credential problem.

Source

Thrown at common/data_source/blob_connector.py:340

        except Exception as e:
            error_code = getattr(e, "response", {}).get("Error", {}).get("Code", "")
            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="",
    )

View on GitHub (pinned to 554fb1133a)

Solutions

1. Correct bucket_name to the exact bucket name (no 's3://' scheme, no ARN, no trailing path — that is what prefix is for)
2. Verify the bucket exists: aws s3 ls or the provider console, using the same account as the credentials
3. For S3-compatible stores, check endpoint_url points at the deployment that actually hosts the bucket
4. If the bucket lives in another AWS account, ensure cross-account ListBucket access is granted (bucket policy + IAM)

Example fix

// before
connector = BlobStorageConnector(
    bucket_type='s3',
    bucket_name='s3://my-team/docs-bucket/',  # scheme + path
)
// after
connector = BlobStorageConnector(
    bucket_type='s3',
    bucket_name='docs-bucket',
    prefix='my-team/',
)

import re
if not re.fullmatch(r'[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]', bucket_name):
    raise ValueError('bucket_name looks like an ARN/URL or is malformed')
connector = BlobStorageConnector(bucket_type=bt, bucket_name=bucket_name, prefix=prefix)

def is_plain_bucket_name(name: str) -> bool:
    return '://' not in name and not name.startswith('arn:') and bool(name.strip('/'))

try:
    connector.validate_connector_settings()
except ConnectorValidationError as e:
    if 'does not exist' in str(e):
        raise ConfigError('check bucket spelling, account, and endpoint_url') from e
    raise

When it happens

Trigger: Typo in bucket_name; bucket in another account without cross-account ListBucket permission (S3 returns 403 in that case, but some setups yield 404); wrong endpoint/region for S3-compatible stores so the endpoint serves a different namespace; bucket recently deleted; prefix vs bucket confusion (passing 's3://bucket/prefix' as the name).

Common situations: Copying the bucket ARN instead of the name into config; environment mismatch (staging bucket name used in prod config); MinIO endpoint_url pointing at the wrong deployment so the bucket genuinely is absent there; renamed bucket after a migration.

Related errors

• main() must return a value. Use null for an empty result.
• main() returned a non-JSON-serializable value.
• message.compileNotSupported
• Failed to fetch search detail
• {} not supported, should be a float number in range [0, 1]

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