How to use waiter functionality for bucket_not_exists using Boto3 and AWS Client?

The bucket_not_exists waiter in Boto3 allows you to wait until an S3 bucket does not exist. This is useful for ensuring a bucket is deleted before proceeding with operations that require the bucket name to be available.

How Waiters Work

Waiters are objects that poll AWS resources until a desired state is reached. The bucket_not_exists waiter checks every 5 seconds (by default) for up to 20 attempts to confirm a bucket doesn't exist. You can customize the polling interval and maximum attempts using WaiterConfig.

Syntax

waiter = s3_client.get_waiter('bucket_not_exists')
waiter.wait(Bucket='bucket-name', WaiterConfig={'Delay': seconds, 'MaxAttempts': attempts})

Example

The following example demonstrates using the waiter to check if buckets do not exist ?

import boto3
from botocore.exceptions import ClientError, WaiterError

def check_bucket_not_exists(bucket_name):
    session = boto3.session.Session()
    s3_client = session.client('s3')
    
    try:
        waiter = s3_client.get_waiter('bucket_not_exists')
        waiter.wait(Bucket=bucket_name,
                   WaiterConfig={
                       'Delay': 2,      # Check every 2 seconds
                       'MaxAttempts': 5  # Try 5 times maximum
                   })
        print(f'Bucket does not exist: {bucket_name}')
        return True
        
    except WaiterError as e:
        print(f'Bucket still exists after max attempts: {bucket_name}')
        return False
        
    except ClientError as e:
        print(f'AWS client error: {e}')
        return False
        
    except Exception as e:
        print(f'Unexpected error: {e}')
        return False

# Test with different bucket names
print("Testing non-existent bucket:")
result1 = check_bucket_not_exists("my-non-existent-bucket-12345")

print("\nTesting bucket that might exist:")
result2 = check_bucket_not_exists("common-bucket-name")

Testing non-existent bucket:
Bucket does not exist: my-non-existent-bucket-12345
True

Testing bucket that might exist:
Bucket still exists after max attempts: common-bucket-name
False

Parameters

Exception Handling

The waiter raises a WaiterError if the bucket still exists after maximum attempts. Always handle this exception to prevent your program from crashing ?

import boto3
from botocore.exceptions import WaiterError

def wait_for_bucket_deletion(bucket_name):
    s3_client = boto3.client('s3')
    waiter = s3_client.get_waiter('bucket_not_exists')
    
    try:
        print(f"Waiting for bucket '{bucket_name}' to be deleted...")
        waiter.wait(Bucket=bucket_name)
        print("Bucket successfully deleted!")
        
    except WaiterError:
        print("Timeout: Bucket still exists after waiting period")

# Example usage
wait_for_bucket_deletion("test-bucket-name")

Waiting for bucket 'test-bucket-name' to be deleted...
Bucket successfully deleted!

Common Use Cases

• After bucket deletion: Confirm a bucket is fully deleted before recreating it
• Cleanup operations: Ensure resources are properly removed
• Deployment scripts: Wait for old resources to be removed before deploying new ones

Conclusion

The bucket_not_exists waiter provides a reliable way to wait for bucket deletion in AWS S3. Use WaiterConfig to customize polling behavior and always handle WaiterError exceptions for robust error handling.