AWS API Gateway "Invalid mapping expression" in CI

API Gateway rejected a request or response parameter mapping because the expression is not a valid method.request / integration.request location. The mapping grammar is strict and the path is malformed.

What this error means

put-integration or put-method-request fails with "BadRequestException: Invalid mapping expression specified: ..." naming the bad expression.

aws

An error occurred (BadRequestException) when calling the PutIntegration operation:
Invalid mapping expression specified: method.request.header

Common causes

The mapping path is incomplete

A location like method.request.header is missing the name segment; it must be method.request.header.Authorization.

The wrong location keyword

Using querystring instead of querystring.<name>, or mixing method.request with integration.request incorrectly, breaks the grammar.

How to fix it

Write the full mapping expression

Use the form method.request.<location>.<name> for inputs.
Use integration.request.<location>.<name> for the backend side.
Re-apply the integration with the corrected expression.

Terminal

aws apigateway put-integration \
  --rest-api-id $API_ID --resource-id $RES_ID --http-method GET --type HTTP \
  --request-parameters '{"integration.request.header.X-User":"method.request.header.Authorization"}'

Validate mappings in the OpenAPI source

When mappings live in OpenAPI, keep the location plus name in requestParameters so the import does not reject them.

openapi.yaml

requestParameters:
  integration.request.header.X-User: method.request.header.Authorization

How to prevent it

Always include the trailing parameter name in mapping expressions.
Keep request mappings in version-controlled OpenAPI for review.
Test mappings against a dev API before deploying to a stage.