Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Flutter web call to an AWS API Gateway endpoint is blocked by CORS

ErrorCross-Origin Request Blocked

Short answer

API Gateway handles CORS differently by type. With a REST API proxy integration, your Lambda must return the CORS headers. With a REST non-proxy integration, you need an OPTIONS method that returns them. An HTTP API has its own CORS setting and ignores backend headers. Check the type, then fix that layer.

  • Applies to Flutter 3.3x stable (web), Amazon API Gateway REST and HTTP APIs
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Send the preflight request by hand and look at the status and the response headers. It shows whether the gateway answers OPTIONS at all, and which headers come back.

    curl -i -X OPTIONS "https://API_ID.execute-api.REGION.amazonaws.com/STAGE/items" \
      -H "Origin: https://app.example.com" \
      -H "Access-Control-Request-Method: POST" \
      -H "Access-Control-Request-Headers: authorization,content-type"
  2. 2Match what you see, then jump to its fix

    1. 1The call works in curl or Postman, fails in the browser, and the API uses Lambda proxy or HTTP proxy integrationREST API with proxy integration: the Lambda does not return the headersFix
    2. 2The OPTIONS request in the first step returns 403 or 404, or a response without the three CORS headersREST API without proxy integration: no working OPTIONS methodFix
    3. 3The API type is HTTP API, and the Lambda already returns CORS headers that have no effectHTTP API: CORS is not configured on the API, or backend headers are ignoredFix
    4. 4Preflight returns 401 or 403 while normal calls with a token workHTTP API with a $default route and an authorizer rejects the preflightFix

What does the error look like?

  • Cross-Origin Request Blocked
  • Access-Control-Allow-Origin header missing from the API Gateway response

Cause 1 of 4

REST API with proxy integration: the Lambda does not return the headers

1Check

A proxy integration does not build an integration response, so the backend itself must send the CORS headers. Look at what your function returns.

aws lambda get-function-configuration --function-name my-fn --query Handler

2Fix

Return Access-Control-Allow-Origin, Access-Control-Allow-Methods and Access-Control-Allow-Headers from the function, on every response.

export const handler = async (event) => ({
  statusCode: 200,
  headers: {
    "Access-Control-Allow-Origin": "https://app.example.com",
    "Access-Control-Allow-Headers": "Content-Type,Authorization",
    "Access-Control-Allow-Methods": "OPTIONS,POST,GET",
  },
  body: JSON.stringify({ ok: true }),
});

3Verify

Repeat the request from the browser; the response carries the headers.

curl -i https://API_ID.execute-api.REGION.amazonaws.com/STAGE/items -H "Origin: https://app.example.com"

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 4

REST API without proxy integration: no working OPTIONS method

1Check

A non-simple request (a JSON POST, or any request with an Authorization header) makes the browser send an OPTIONS preflight first. The API needs a method that answers it.

aws apigateway get-resources --rest-api-id API_ID

2Fix

Create an OPTIONS method with a mock integration. Add Access-Control-Allow-Headers, Access-Control-Allow-Methods and Access-Control-Allow-Origin to the 200 method response, and give them values. Return Access-Control-Allow-Origin on the real methods too, for at least the 200 responses. The console's Enable CORS action does part of this and does not always finish the job.

Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'
Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'
Access-Control-Allow-Origin: 'https://app.example.com'

3Verify

The preflight from the first step now returns 200 with the three headers.

curl -i -X OPTIONS https://API_ID.execute-api.REGION.amazonaws.com/STAGE/items -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST"

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 4

HTTP API: CORS is not configured on the API, or backend headers are ignored

1Check

Once you configure CORS on an HTTP API, API Gateway answers preflight requests itself and ignores CORS headers from the backend. Read the current setting.

aws apigatewayv2 get-api --api-id API_ID --query CorsConfiguration

2Fix

Set the origins, methods and headers on the API. Include authorization in allowHeaders when the app sends a bearer token, and use the exact origin of the Flutter web app.

aws apigatewayv2 update-api --api-id API_ID \
  --cors-configuration AllowOrigins="https://app.example.com",AllowMethods="GET,POST",AllowHeaders="authorization,content-type"

3Verify

The preflight request returns the configured headers. A request must carry an origin header, and for OPTIONS also Access-Control-Request-Method.

curl -i -X OPTIONS https://API_ID.execute-api.REGION.amazonaws.com/items -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST"

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 4 of 4

HTTP API with a $default route and an authorizer rejects the preflight

1Check

The $default route catches every unmatched request, including OPTIONS. With an authorizer attached, the preflight (which carries no token) is refused.

aws apigatewayv2 get-routes --api-id API_ID --query 'Items[].RouteKey'

2Fix

Add an OPTIONS /{proxy+} route that does not require authorization and attach an integration to it. It has higher priority than $default.

aws apigatewayv2 create-route --api-id API_ID --route-key 'OPTIONS /{proxy+}' --authorization-type NONE

3Verify

The preflight now returns a success status, and the real call follows.

curl -i -X OPTIONS https://API_ID.execute-api.REGION.amazonaws.com/items -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: POST"

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Decide per API type where CORS lives (Lambda, OPTIONS method or API setting) and write it in the README.
  • Use the exact origin of the web app, not * , if the app sends credentials or tokens.
  • Add the preflight curl command to your deploy checks.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Google Play says the app does not support 16 KB memory pages

check_elf_alignment.sh reports UNALIGNED for a library under lib/arm64-v8a

Google Play requires apps that target Android 15 or higher and ship native .so libraries to run on devices with 16 KB memory pages; from 1 February 2027 it will block updates that do not.

5 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.