{"id":6530,"library":"aws-error-utils","title":"AWS Error Utils","description":"AWS Error Utils is a Python library that provides error-handling functions to simplify dealing with `botocore.exceptions.ClientError` in boto3 applications. It aims to make AWS service exception handling more Pythonic by allowing direct matching against error codes and operation names, reducing the need to parse nested dictionary structures. The current version is 2.7.0, and it maintains a steady release cadence with minor updates addressing Python version support and new features.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/benkehoe/aws-error-utils","tags":["aws","boto3","botocore","error-handling","exceptions"],"install":[{"cmd":"pip install aws-error-utils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"The library is designed to work with exceptions raised by boto3/botocore.","package":"boto3","optional":false}],"imports":[{"symbol":"catch_aws_error","correct":"from aws_error_utils import catch_aws_error"},{"note":"The 'errors' object is imported directly, and its attributes (e.g., `errors.NoSuchBucket`) are aliases to `catch_aws_error()` calls, not actual exception classes.","wrong":"from aws_error_utils.errors import NoSuchBucket","symbol":"errors","correct":"from aws_error_utils import errors"},{"symbol":"aws_error_matches","correct":"from aws_error_utils import aws_error_matches"},{"symbol":"get_aws_error_info","correct":"from aws_error_utils import get_aws_error_info"}],"quickstart":{"code":"import boto3\nfrom aws_error_utils import catch_aws_error, errors\nimport os\nfrom botocore.exceptions import ClientError\n\n# Configure boto3 client with dummy credentials for local testing, or load from environment\ns3_client = boto3.client(\n    's3',\n    aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', 'test'),\n    aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', 'test'),\n    aws_session_token=os.environ.get('AWS_SESSION_TOKEN'), # Optional\n    region_name=os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')\n)\n\nnon_existent_bucket = \"non-existent-aws-error-utils-test-bucket-12345\"\n\nprint(f\"Attempting to list objects in '{non_existent_bucket}'...\")\ntry:\n    s3_client.list_objects_v2(Bucket=non_existent_bucket)\nexcept catch_aws_error(\"NoSuchBucket\") as e:\n    print(f\"Caught expected AWS error using catch_aws_error: Code={e.code}, Message='{e.message}'\")\nexcept ClientError as e:\n    print(f\"Caught an unexpected ClientError: {e}\")\nexcept Exception as e:\n    print(f\"Caught a generic exception: {e}\")\n\nprint(\"\\nDemonstrating 'errors' class for common error codes (if applicable) (alias to catch_aws_error)...\")\ntry:\n    s3_client.list_objects_v2(Bucket=non_existent_bucket)\nexcept errors.NoSuchBucket as e:\n    print(f\"Caught expected AWS error using errors.NoSuchBucket: Code={e.code}, Message='{e.message}'\")\nexcept ClientError as e:\n    print(f\"Caught an unexpected ClientError via ClientError: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `catch_aws_error` to handle specific AWS `ClientError` exceptions. It attempts to access a non-existent S3 bucket, which typically raises a `NoSuchBucket` error. It also shows the alternative `errors.NoSuchBucket` syntax, which is an alias for `catch_aws_error('NoSuchBucket')`."},"warnings":[{"fix":"Upgrade Python to 3.7 or higher. If upgrading Python is not feasible, pin `aws-error-utils<2.7.0`.","message":"Python 3.6 support was removed in version 2.7. Users on Python 3.6 or earlier must upgrade their Python version or use an older version of `aws-error-utils`.","severity":"breaking","affected_versions":">=2.7.0"},{"fix":"Upgrade Python to 3.6 or higher. If upgrading Python is not feasible, pin `aws-error-utils<2.4.0`.","message":"Python 3.5 support was removed in version 2.4.","severity":"breaking","affected_versions":">=2.4.0"},{"fix":"For error codes containing special characters or periods, always use `except catch_aws_error('Complex.ErrorCode'):` instead of `except errors.ComplexErrorCode:`.","message":"The `errors` class (e.g., `errors.NoSuchBucket`) provides a simpler syntax but is limited to error codes that can be valid Python property names. For complex error codes (e.g., `InvalidInstanceID.NotFound`), you must use the `catch_aws_error()` function directly with the full string code.","severity":"gotcha","affected_versions":"All"},{"fix":"Treat `errors.SomeError` as a convenience function call within an `except` block rather than a standard Python exception class.","message":"`errors.SomeError` is an alias for `catch_aws_error('SomeError')`, not an actual exception class. This means you cannot subclass `errors.SomeError` or use it in `issubclass()` checks.","severity":"gotcha","affected_versions":"All"},{"fix":"Use `except catch_aws_error(aws_error_utils.ALL_CODES, operation_name='GetObject'):` to match all errors from the 'GetObject' operation.","message":"When using `catch_aws_error()`, you must provide an error code. To match an exception exclusively by its `operation_name` (e.g., for all errors from a specific API call), you need to use `aws_error_utils.ALL_CODES` as the error code argument.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install aws-error-utils'.","cause":"The 'aws-error-utils' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'aws_error_utils'"},{"fix":"Ensure compatible versions of 'boto3' and 'botocore' are installed by updating both: 'pip install --upgrade boto3 botocore'.","cause":"A version mismatch between 'boto3' and 'botocore' libraries.","error":"ImportError: cannot import name 'is_s3express_bucket' from 'botocore.utils'"},{"fix":"Check the library's documentation for the updated import path or alternative functions.","cause":"The 'safe_join' function has been removed or relocated in the library being imported.","error":"ImportError: cannot import name 'safe_join'"},{"fix":"Verify that the 'utils' module is correctly implemented and contains the 'process_tweet' function.","cause":"The 'utils' module does not contain a 'process_tweet' function, possibly due to a missing or incorrect import.","error":"ImportError: cannot import name 'process_tweet' from 'utils'"},{"fix":"Rearrange the import statements to avoid circular dependencies or import errors.","cause":"A circular import or incorrect import statement in the code.","error":"ImportError: cannot import name 'display'"}]}