AWS routing debugger

CloudFront API Gateway path debugger for custom domains, Cloud Map, and ECS

Find where an AWS request path changes between the browser, CloudFront, API Gateway custom-domain mapping, HTTP API routes, parameter mapping, private integrations, Cloud Map, and your ECS backend.

Use this tool to debug issues such as /api being forwarded to the backend, route matches that still return 404, CloudFront Function rewrite problems, and overwrite:path = $request.path fixes.

1. Enter the browser request URL

2. Debug CloudFront behavior, origin path, and URI rewrite

2.1 CloudFront behavior + origin path

CloudFront behavior selects the origin but does not strip the prefix. The origin path is prepended.

2.2 CloudFront Function URI rewrite

Optional CloudFront Function replace

Simulates request.uri = request.uri.replace(...) before the request is forwarded to API Gateway.

Old solution example: mode RegExp replace, search ^/api(?=/|$), empty replacement. This changes /api/endpoint → /endpoint.

3. Test API Gateway custom domain mapping

API mapping can make API Gateway match the route /endpoint even though the public path is /api/endpoint.

4. Match API Gateway HTTP API routes

5. Debug private integration and parameter mapping

In your support case, the default behavior is best modeled as the private integration receiving /api/endpoint, while overwrite:path = $request.path sends /endpoint.

Common CloudFront and API Gateway debugging scenarios

Request path flow from CloudFront to backend

Calculating

API Gateway route match and backend path result

Rules used by the model
  • CloudFront path pattern selects the behavior/origin from the original viewer URI and does not strip the prefix. A CloudFront Function is associated with the matched behavior, so rewrite changes the forwarded path but should not make the behavior match fail.
  • The origin path is prepended before the request path.
  • CloudFront Function rewrite is simulated with JavaScript replace, either string or RegExp.
  • API Gateway custom-domain API mapping selects the API/stage based on the mapping path. The route path can therefore become /endpoint even when the public path is /api/endpoint.
  • For HTTP API private integrations, the path that reaches the backend can differ from the route path. In your AWS Support case, the backend receives /api/ecos/123 even though the backend route is /ecos/{id}.
  • overwrite:path = $request.path is simulated as the private integration receiving API Gateway's clean route/request path, e.g. /endpoint.
  • The disabled default endpoint affects the execute-api hostname, not the custom-domain/API mapping path in this chain.

How this AWS path debugger helps

This tool shows each request path step by step so you can compare the public URL with the path that API Gateway uses for route matching and the path that reaches your backend service.

  • Check whether CloudFront keeps, rewrites, or prepends path segments.
  • Verify how an API Gateway custom-domain mapping changes the route path.
  • See when a private integration forwards the public prefix to Cloud Map or ECS.
  • Test whether overwrite:path = $request.path sends the backend path your service expects.
CloudFront and API Gateway path debugging FAQ

Does a CloudFront behavior path pattern strip the matched prefix?

No. A behavior path pattern selects a behavior and origin. It does not remove the prefix from the URI by itself.

Why does my API Gateway route match but my ECS service still returns 404?

The route path used by API Gateway can differ from the path forwarded to a private integration. Your backend may receive a prefix such as /api even when the matched API route is /endpoint.

When should I test overwrite:path?

Test overwrite:path = $request.path when API Gateway matches the route but the backend receives a path that includes the public API mapping prefix or another unwanted segment.