{"record":{"id":"76945a8c7cc269fd","repo":"infiniflow/ragflow","slug":"bucket-self-bucket-name-does-not-exist-or-cann","errorCode":null,"errorMessage":"Bucket '{self.bucket_name}' does not exist or cannot be found.","messagePattern":"Bucket '(.+?)' does not exist or cannot be found\\.","errorType":"validation","errorClass":"ConnectorValidationError","httpStatus":404,"severity":"error","filePath":"common/data_source/blob_connector.py","lineNumber":340,"sourceCode":"        except Exception as e:\n            error_code = getattr(e, \"response\", {}).get(\"Error\", {}).get(\"Code\", \"\")\n            status_code = getattr(e, \"response\", {}).get(\"ResponseMetadata\", {}).get(\"HTTPStatusCode\")\n\n            # Common S3 error scenarios\n            if error_code in [\n                \"AccessDenied\",\n                \"InvalidAccessKeyId\",\n                \"SignatureDoesNotMatch\",\n            ]:\n                if status_code == 403 or error_code == \"AccessDenied\":\n                    raise InsufficientPermissionsError(f\"Insufficient permissions to list objects in bucket '{self.bucket_name}'. Please check your bucket policy and/or IAM policy.\")\n                if status_code == 401 or error_code == \"SignatureDoesNotMatch\":\n                    raise CredentialExpiredError(\"Provided blob storage credentials appear invalid or expired.\")\n\n                raise CredentialExpiredError(f\"Credential issue encountered ({error_code}).\")\n\n            if error_code == \"NoSuchBucket\" or status_code == 404:\n                raise ConnectorValidationError(f\"Bucket '{self.bucket_name}' does not exist or cannot be found.\")\n\n            raise ConnectorValidationError(f\"Unexpected S3 client error (code={error_code}, status={status_code}): {e}\")\n\n\nif __name__ == \"__main__\":\n    # Example usage\n    credentials_dict = {\n        \"aws_access_key_id\": os.environ.get(\"AWS_ACCESS_KEY_ID\"),\n        \"aws_secret_access_key\": os.environ.get(\"AWS_SECRET_ACCESS_KEY\"),\n    }\n\n    # Initialize connector\n    connector = BlobStorageConnector(\n        bucket_type=os.environ.get(\"BUCKET_TYPE\") or \"s3\",\n        bucket_name=os.environ.get(\"BUCKET_NAME\") or \"yyboombucket\",\n        prefix=\"\",\n    )\n","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/blob_connector.py#L322-L358","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Correct bucket_name to the exact bucket name (no 's3://' scheme, no ARN, no trailing path — that is what prefix is for)","Verify the bucket exists: aws s3 ls or the provider console, using the same account as the credentials","For S3-compatible stores, check endpoint_url points at the deployment that actually hosts the bucket","If the bucket lives in another AWS account, ensure cross-account ListBucket access is granted (bucket policy + IAM)"],"exampleFix":"// before\nconnector = BlobStorageConnector(\n    bucket_type='s3',\n    bucket_name='s3://my-team/docs-bucket/',  # scheme + path\n)\n// after\nconnector = BlobStorageConnector(\n    bucket_type='s3',\n    bucket_name='docs-bucket',\n    prefix='my-team/',\n)","handlingStrategy":"validation","validationCode":"import re\nif not re.fullmatch(r'[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]', bucket_name):\n    raise ValueError('bucket_name looks like an ARN/URL or is malformed')\nconnector = BlobStorageConnector(bucket_type=bt, bucket_name=bucket_name, prefix=prefix)","typeGuard":"def is_plain_bucket_name(name: str) -> bool:\n    return '://' not in name and not name.startswith('arn:') and bool(name.strip('/'))","tryCatchPattern":"try:\n    connector.validate_connector_settings()\nexcept ConnectorValidationError as e:\n    if 'does not exist' in str(e):\n        raise ConfigError('check bucket spelling, account, and endpoint_url') from e\n    raise","preventionTips":["Store bucket name and prefix as separate fields and validate that the name contains no '/', ':', or 'arn:'","For S3-compatible stores, confirm endpoint_url points at the deployment hosting the bucket before saving config"],"tags":["configuration","s3","bucket","validation"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}