Event Handler bug audit: 34 reproduced bugs grouped into 14 issues

[leandrodamascena]

I spent some time auditing the Event Handler utility looking for bugs. I read the code, wrote a reproduction for every suspect, ran all of them inside a real Lambda (Python 3.13, develop code) and, for the ones that depend on the real event shape, through a real API Gateway REST API, HTTP API with a named stage, and an AppSync Events API. Everything below reproduces. None of these has an open issue yet.

I grouped them by root cause so each group can become one issue and one PR. Severity is my call: High breaks a customer in normal use or bypasses validation, Medium contradicts the docs or HTTP semantics but has a workaround, Low is an edge case or only affects the generated schema.

I'll open individual issues from this list. If you hit any of these, or disagree with a severity, comment here.

---

High

1. APIGatewayHttpResolver returns 404 for every route when the stage is not $default and the path has no stage prefix

utilities/data_classes/api_gateway_proxy_event.py:317

APIGatewayProxyEventV2.path does rawPath[len("/" + stage):] without checking that rawPath starts with the stage. With a custom domain API mapping (or SAM local) rawPath is /my/path and stage is dev, so path becomes path and nothing matches.

ev["requestContext"]["stage"] = "dev"; ev["rawPath"] = "/my/path"
app = APIGatewayHttpResolver()
@app.get("/my/path")
def r(): return {"ok": True}
app.resolve(ev, None)  # 404, event.path == "path"

Note: I confirmed this in the Lambda runtime with the event shape AWS documents for custom domains, not through a live custom domain.

2. Body validation: multipart with non-ASCII text crashes, and a JSON array is accepted for an object parameter

middlewares/openapi_validation.py:221-241, 541, 800

• multipart/form-data with a text field containing café raises UnicodeDecodeError, which escapes because except ValueError: raise re-raises Unicode errors. Missing boundary raises a bare ValueError. Real API Gateway returns 502. Expected 422/415.
• A JSON array body [{"name":"a","price":1},{"name":"b","price":2}] sent to def create(item: Item) returns 200 with the first element. The list unwrapping meant for form values is applied to JSON bodies. Expected 422.
• Content-Disposition with filename= before name= is misparsed (find('name="') matches inside filename="), giving 422 missing.

3. Exception handlers hijack the default 404 and bypass _to_response

api_gateway.py:2847, 2952

• @app.exception_handler(Exception), which the docs suggest as a catch-all, turns every unmatched route into 500: not_found_handler synthesizes a NotFoundError() and walks the MRO, so the generic handler receives it. Real API: GET /nope → 500 generic handler got NotFoundError().
• _call_exception_handler wraps handler(exp) without _to_response. On ALB a handler returning Response(body=None) emits "body": null (502 from ALB); the same Response returned from a route emits "".
• A handler returning a dict or tuple crashes with AttributeError: 'tuple' object has no attribute 'is_json', masking the original exception. Real API: 502.

---

Medium

4. AppSync Events: UnauthorizedException in a non-aggregate publish handler returns HTTP 200 and leaks the message

events_appsync/appsync_events.py:257, 316

The docs say raising UnauthorizedException fails the invocation and the publisher gets 403, and the documented example uses the default aggregate=False. In that mode the exception is caught per event. Real AppSync Events API:

non-aggregate: HTTP 200 {"failed":[{"code":"CustomError","message":"UnauthorizedException - not allowed"}, ...],"successful":[]}
aggregate=True: HTTP 401 {"errors":[{"errorType":"UnauthorizedException","message":"Not authorized to access channel agg"}]}

Events are not delivered in either case, so this is not a bypass. But the status code is wrong and the internal exception message reaches the publisher. Same for async_on_publish.

5. Route rules are compiled as unescaped regex, and regex strip_prefixes replaces every occurrence

api_gateway.py:2778, 2809

• /items.json matches /itemsXjson (200). A literal /a+b returns 404 for /a+b. Confirmed through a real REST API.
• strip_prefixes=[re.compile(r"/v[1-9]+")] on /v1/users/v2 strips both, path becomes /users, 404. re.sub has no count=1 and no anchor.

6. Header validation is inconsistent across resolvers

openapi_validation.py:144, 636, 644 + data classes

• list[str] header with a single value → 422 list_type on HTTP API, Function URL, ALB and VPC Lattice v1. Two values work. REST v1 works. Real HTTP API confirmed. This is the docs example working_with_headers_multi_value.py on a different resolver.
• Repeated header lines for a scalar str → 422 on REST v1 / ALB, but joined "a,b" on HTTP API.
• Content-Type: Application/JSON → 415 on every resolver. Media types are case-insensitive. +json suffixes are rejected too.

7. Response and compression edge cases

api_gateway.py:364, 755, 838

• Response(content_type=APPLICATION_JSON, body=b'...') raises TypeError when enable_validation=False. The docstring says bytes are base64 encoded.
• Response(headers={"content-type": "application/json"}, body={...}) with lowercase header: is_json() misses it, the dict is returned unserialized, API Gateway returns 502.
• Accept-Encoding: gzip;q=0 still compresses; GZIP does not. Confirmed through a real REST API.

8. Async middleware: class-based async def handler leaks a coroutine, wrap_middleware_async raises IndexError

middlewares/async_utils.py:101, 158

• A BaseMiddlewareHandler subclass with async def handler in resolve_async ends with TypeError: Object of type coroutine is not JSON serializable. The docs say both class-based and async middlewares work.
• wrap_middleware_async with a sync middleware that short-circuits (returns a Response without calling next) raises IndexError.

9. HttpResolverLocal cannot be used as a Lambda handler and crashes on binary bodies

http_resolver.py:72, 270, 348

• handler = app as the docs example suggests fails with TypeError (the __call__ is ASGI-only). app.resolve() with an HTTP API or Function URL event raises KeyError: 'httpMethod'.
• A binary request body raises UnicodeDecodeError.

10. CORS response is missing Vary: Origin when echoing a specific allowed origin

api_gateway.py:232

With allow_origin="https://a.com", extra_origins=["https://b.com"], the response carries Access-Control-Allow-Origin: https://a.com and no Vary. A shared cache can serve origin A's response to origin B. Confirmed through a real HTTP API.

---

Low

11. OpenAPI schema inaccuracies

openapi/schema_generator.py:373, 506, openapi/types.py:28, openapi/encoders.py:330, openapi_validation.py:422, api_gateway.py:1813

• responses={404: {"description": "nf"}} without content gets the handler's return model injected for every status code.
• A Pydantic model used as Query(): int | None, list[str] and Enum fields come out as {"type": "string"}.
• The ValidationError component requires msg, which is neither defined nor returned by the real 422 body.
• openapi_extensions at root and operation level skip the x- prefix check that Server enforces.
• Path(alias="ident") can never be satisfied (422 missing) and emits a parameter name not in the path template.
• Decimal("NaN") in a response raises TypeError instead of SerializationError.

12. Bedrock Agent: every event parameter passed as kwarg when validation is off, null content type key

bedrock_agent.py:52, 350

• With enable_validation=False, a query parameter not in the handler signature raises TypeError: unexpected keyword argument.
• A Response without content type produces "responseBody": {"null": {...}}.

13. AppSync: decorator returns None on invalid path, context not cleared when an exception handler runs

events_appsync/_registry.py:56, appsync.py:160

• @app.on_publish("/default/*/sub") warns and returns None, so the decorated function disappears.
• AppSyncResolver.resolve() returns the exception handler result before clear_context(), so app.context leaks into the next invocation.

14. Miscellaneous

api_gateway.py:3185, lambda_function_url.py:57, depends.py:121

• Router silently overwrites a duplicate route (last wins); the resolver warns and keeps the first.
• LambdaFunctionUrlResolver._get_base_path checks http.method instead of http.path. Unreachable today since Function URLs only use $default.
• Depends(SomeClass) ignores the __init__ signature, so a class dependency cannot receive Request or a nested Depends.

[leandrodamascena]

Opened the issues from this list:

High

• Bug: APIGatewayHttpResolver returns 404 for every route when the stage is not $default and rawPath has no stage prefix #8577 HTTP API 404 with named stage behind a custom domain (1)
• Bug: body validation crashes on non-ASCII multipart data and accepts a JSON array for an object parameter #8578 body validation: multipart non-ASCII crash, JSON array accepted for object (2)
• Bug: exception handlers hijack the default 404 and bypass _to_response (body null on ALB, dict/tuple crash) #8579 exception handlers hijack 404 and bypass _to_response (3)

Medium

• Bug: routing and Response issues: unescaped route regex, regex strip_prefixes, gzip q=0, bytes JSON body, is_json() casing, missing Vary: Origin #8580 routing and Response: unescaped regex, strip_prefixes, gzip q=0, bytes body, is_json() casing, Vary: Origin (5, 7, 10)
• Bug: header validation is inconsistent across resolvers (single-value list, repeated headers, Content-Type casing) #8581 header validation inconsistent across resolvers (6)
• Bug: AppSync Events swallows UnauthorizedException in non-aggregate handlers, class-based async middleware leaks a coroutine, HttpResolverLocal is not usable as a Lambda handler #8582 AppSync Events UnauthorizedException, class-based async middleware, HttpResolverLocal (4, 8, 9)

Low

• Bug: OpenAPI schema inaccuracies (responses content, Pydantic Query models, ValidationError.msg, x- extensions, Path alias, Decimal NaN) #8583 OpenAPI schema inaccuracies (11)
• Bug: Bedrock Agent kwargs and null content type, AppSync decorator returns None and context leak, Router duplicates, Function URL base path, Depends() with a class #8584 Bedrock Agent, AppSync decorator/context, Router duplicates, Function URL, Depends() with a class (12, 13, 14)