botocore

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• get_session
  wrong

  import botocore; botocore.session()

  correct

  import botocore.session; session = botocore.session.get_session()

  The top-level `botocore` namespace does not expose session or client constructors directly. Always import `botocore.session` and call `get_session()`.

• ClientError
  wrong

  from botocore.vendored.requests.exceptions import ...

  correct

  from botocore.exceptions import ClientError

  All vendored requests/urllib3 exception imports (botocore.vendored.*) were removed. Use botocore.exceptions for all exception classes.

• BotoCoreError

  from botocore.exceptions import BotoCoreError

  Base class for all client-side botocore errors (config, validation, connectivity). Catch alongside ClientError for complete coverage.

• Config

  from botocore.config import Config

  Used to configure retries, timeouts, signature version, addressing style, and other per-client options passed via session.create_client(..., config=Config(...)).

• Session (low-level)

  import botocore.session; s = botocore.session.Session()

  botocore.session.Session is the raw low-level session. boto3.session.Session wraps it and is the preferred interface for most users.

Quickstart verified last tested: 2026-04-23

Create a botocore session, build an S3 client using environment-variable credentials, and handle errors idiomatically by inspecting the structured error response.

import os
import botocore.session
from botocore.config import Config
from botocore.exceptions import ClientError, BotoCoreError

# Build session — credentials resolved from env, ~/.aws/credentials, or IAM role
session = botocore.session.get_session()

client = session.create_client(
    's3',
    region_name=os.environ.get('AWS_DEFAULT_REGION', 'us-east-1'),
    aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),
    aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),
    config=Config(
        retries={'max_attempts': 5, 'mode': 'adaptive'},
        connect_timeout=5,
        read_timeout=10,
    ),
)

try:
    response = client.list_buckets()
    for bucket in response.get('Buckets', []):
        print(bucket['Name'])
except ClientError as e:
    # AWS service-side error — inspect the structured code, NOT the string message
    code = e.response['Error']['Code']
    msg  = e.response['Error']['Message']
    print(f'AWS error [{code}]: {msg}')
    if code == 'AccessDenied':
        raise PermissionError('Check IAM permissions') from e
except BotoCoreError as e:
    # Client-side error (bad config, network, credential resolution)
    print(f'botocore client error: {e}')
    raise