infiniflow/ragflow · error · ConnectorValidationError

No bucket name was provided in connector settings.

Error message

No bucket name was provided in connector settings.

What it means

Raised by BlobStorageConnector.validate_connector_settings when self.bucket_name is falsy after construction. The constructor strips whitespace (bucket_name.strip()), so a name of '', ' ', or None produces this ConnectorValidationError. It fires before the lightweight list_objects_v2(MaxKeys=1) probe, so the user gets a clear config message instead of a confusing S3 error.

Source

Thrown at common/data_source/blob_connector.py:316

    def poll_source(self, start: SecondsSinceUnixEpoch, end: SecondsSinceUnixEpoch) -> GenerateDocumentsOutput:
        """Poll source to get documents"""
        if self.s3_client is None:
            raise ConnectorMissingCredentialError("Blob storage")

        start_datetime = datetime.fromtimestamp(start, tz=timezone.utc)
        end_datetime = datetime.fromtimestamp(end, tz=timezone.utc)

        for batch in self._yield_blob_objects(start_datetime, end_datetime):
            yield batch

    def validate_connector_settings(self) -> None:
        """Validate connector settings"""
        if self.s3_client is None:
            raise ConnectorMissingCredentialError("Blob storage credentials not loaded.")

        if not self.bucket_name:
            raise ConnectorValidationError("No bucket name was provided in connector settings.")

        try:
            # Lightweight validation step
            self.s3_client.list_objects_v2(Bucket=self.bucket_name, Prefix=self.prefix, MaxKeys=1)

        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":

View on GitHub (pinned to 554fb1133a)

Solutions

1. Set a non-empty bucket name in the connector configuration
2. Check for typos/renames in the config key or env var that supplies the bucket name
3. Trim input and reject empty values in the config UI/handler before constructing the connector
4. Note the name is stripped at construction — a whitespace-only name will still fail, so fix the source value

Example fix

// before
connector = BlobStorageConnector(
    bucket_type='s3',
    bucket_name=os.environ.get('BUCKET_NAME', ''),  # unset -> ''
)
// after
bucket = os.environ['BUCKET_NAME'].strip()  # fails fast if unset
connector = BlobStorageConnector(bucket_type='s3', bucket_name=bucket)

bucket_name = (config.get('bucket_name') or '').strip()
if not bucket_name:
    raise ValueError('bucket_name is required')
connector = BlobStorageConnector(bucket_type=bt, bucket_name=bucket_name)

def is_valid_bucket_name(name: str | None) -> bool:
    return bool(name and name.strip())

try:
    connector.validate_connector_settings()
except ConnectorValidationError as e:
    if 'No bucket name' in str(e):
        raise ConfigError('bucket_name missing in connector config') from e
    raise

When it happens

Trigger: Constructing the connector with bucket_name='' or a whitespace-only string (the strip() in __init__ reduces it to ''), or passing None. Then calling validate_connector_settings().

Common situations: Connector config form submitted with an empty bucket field; environment variable for the bucket name unset (defaults to ''); the bucket name read from a YAML/JSON config key that was renamed so it silently resolves to empty.

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/d4e545161be78f28. Report an issue: GitHub.