boto/boto3 · error · NotImplementedError

Search path hits shape type {shape.type_name} from {item}

Error message

Search path hits shape type {shape.type_name} from {item}

What it means

Raised by build_empty_response() when constructing an empty placeholder for a resource action whose JMESPath search_path traverses into a shape type other than 'structure' or 'list' (e.g. map, string, integer, blob). boto3 walks the dotted search path component by component to find the terminal shape so it can return the right empty value ({} , [], or None), and it only knows how to descend into structures and lists. Hitting any other shape type means the resource model's path definition is incompatible with this code, so it raises NotImplementedError rather than guessing.

Source

Thrown at boto3/resources/response.py:112

    response = None

    operation_model = service_model.operation_model(operation_name)
    shape = operation_model.output_shape

    if search_path:
        # Walk the search path and find the final shape. For example, given
        # a path of ``foo.bar[0].baz``, we first find the shape for ``foo``,
        # then the shape for ``bar`` (ignoring the indexing), and finally
        # the shape for ``baz``.
        for item in search_path.split('.'):
            item = item.strip('[0123456789]$')

            if shape.type_name == 'structure':
                shape = shape.members[item]
            elif shape.type_name == 'list':
                shape = shape.member
            else:
                raise NotImplementedError(
                    f'Search path hits shape type {shape.type_name} from {item}'
                )

    # Anything not handled here is set to None
    if shape.type_name == 'structure':
        response = {}
    elif shape.type_name == 'list':
        response = []
    elif shape.type_name == 'map':
        response = {}

    return response


class RawHandler:
    """
    A raw action response handler. This passed through the response
    dictionary, optionally after performing a JMESPath search if one

View on GitHub (pinned to c7b4afac23)

Solutions

Upgrade boto3 (and botocore) to the latest release so the bundled resource model and service model stay in sync: pip install -U boto3 botocore.
If you control the resource model / are developing one, shorten or correct the search_path so it terminates on a structure or list shape, or handle the scalar case upstream.
Switch from the resource API to the low-level client API (boto3.client(...).<operation>()) which does not run build_empty_response and returns the raw response dict.
If the error is consistent, file a boto3 issue with the service name, action, and boto3/botocore versions.

Example fix

// before
ec2 = boto3.resource('ec2')
result = ec2.meta.client.some_action()  # triggers build_empty_response

# after
client = boto3.client('ec2')
result = client.some_action()  # raw response, no empty-response shape walking

Defensive patterns

Strategy: try-catch

Validate before calling

available = boto3.session.Session().get_available_resources()
if service_name not in available:
    client = boto3.client(service_name)  # avoid the resource path entirely

Type guard

def is_resource_supported(service_name: str) -> bool:
    return service_name in boto3.session.Session().get_available_resources()

Try / catch

try:
    result = resource.action()
except NotImplementedError as e:
    if 'Search path hits shape type' in str(e):
        # resource model / data mismatch; fall back to client API
        result = boto3.client(service_name).action()

Prevention

Keep boto3 and botocore versions in sync (pip install -U boto3 botocore) so resource models match service models.
Prefer the low-level client API for actions whose empty-response shape is uncertain.
Pin botocore to a version compatible with your pinned boto3 to avoid data/model drift.

When it happens

Trigger: Calling a resource action (e.g. collection.batch_delete(), a custom action, or an action whose response path ends in a map/scalar) where the underlying service-model output shape along the configured search path is a map or primitive. It surfaces specifically when boto3 needs to synthesize an empty response (the operation returned nothing) and must resolve the terminal shape type via build_empty_response().

Common situations: Using a resource action against an older/newer API-version data file whose path no longer aligns with the service model; a resource model definition bug shipped in a boto3 version; pinning a botocore data version that mismatches the bundled boto3 resource definitions.

Related errors

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