boto/boto3 · error · UnknownAPIVersionError

The '{service_name}' resource does not support an API versio

Error message

The '{service_name}' resource does not support an API version of: {bad_api_version}
Valid API versions are: {available_api_versions}

What it means

Raised as boto3.exceptions.UnknownAPIVersionError by Session.resource() when an explicit api_version argument does not match any resource data file for the service (DataNotFoundError from load_service_model). resource() must pair a resource model with a client model of the same API version, so an unrecognized version is rejected and the valid versions are listed in the message.

Source

Thrown at boto3/session.py:441

        """
        try:
            resource_model = self._loader.load_service_model(
                service_name, 'resources-1', api_version
            )
        except UnknownServiceError:
            available = self.get_available_resources()
            has_low_level_client = (
                service_name in self.get_available_services()
            )
            raise ResourceNotExistsError(
                service_name, available, has_low_level_client
            )
        except DataNotFoundError:
            # This is because we've provided an invalid API version.
            available_api_versions = self._loader.list_api_versions(
                service_name, 'resources-1'
            )
            raise UnknownAPIVersionError(
                service_name, api_version, ', '.join(available_api_versions)
            )

        if api_version is None:
            # Even though botocore's load_service_model() can handle
            # using the latest api_version if not provided, we need
            # to track this api_version in boto3 in order to ensure
            # we're pairing a resource model with a client model
            # of the same API version.  It's possible for the latest
            # API version of a resource model in boto3 to not be
            # the same API version as a service model in botocore.
            # So we need to look up the api_version if one is not
            # provided to ensure we load the same API version of the
            # client.
            #
            # Note: This is relying on the fact that
            #   loader.load_service_model(..., api_version=None)
            # and loader.determine_latest_version(..., 'resources-1')

View on GitHub (pinned to c7b4afac23)

Solutions

1. Omit api_version to let boto3 resolve the latest paired resource/client version: boto3.resource('service').
2. Read the valid versions listed in the error message and pass one of those exact strings.
3. Upgrade boto3 (and botocore) so the requested newer API version is available.
4. If you specifically need an API version with no resource model, use boto3.client('service', api_version=...) which supports all botocore service-model versions.

Example fix

// before
boto3.resource('s3', api_version='2001-01-01')  # not a valid resource api version

// after
boto3.resource('s3')  # use latest
# or pick from the versions listed in the error:
boto3.resource('s3', api_version='2006-03-01')

session = boto3.session.Session()
valid_versions = session._loader.list_api_versions(service_name, 'resources-1')
if api_version not in valid_versions:
    raise ValueError(f'{api_version} not in {valid_versions}')
resource = session.resource(service_name, api_version=api_version)

def is_valid_resource_api_version(service_name: str, api_version: str) -> bool:
    session = boto3.session.Session()
    versions = session._loader.list_api_versions(service_name, 'resources-1')
    return api_version in versions

from boto3.exceptions import UnknownAPIVersionError
try:
    res = boto3.resource(service_name, api_version=api_version)
except UnknownAPIVersionError as e:
    # e message lists valid versions; retry with the latest
    res = boto3.resource(service_name)

When it happens

Trigger: Calling boto3.resource('service', api_version='YYYY-MM-DD') with a date that is not a valid resource-model API version for that service — a typo, a wrong format, a version newer than the bundled data, or a version that exists only as a botocore service model (not as a boto3 resource model).

Common situations: Hard-coding an api_version from docs that predates the resource model; bumping botocore data without updating boto3 resource data; passing a client-style API version string into resource(); using a version from a different service.

Related errors

• Search path hits shape type {shape.type_name} from {item}
• Unable to locate credentials
• The '{service_name}' resource does not exist. The available
• CRT transfer client is configured but is missing minimum crt
• The following transfer config options are invalid when prefe

AI-assisted analysis of boto/boto3@c7b4afac23 (2026-08-04). Data as JSON: /data/errors/0f4defdda727d7ff.json. Report an issue: GitHub.