Flutter web call to an AWS API Gateway endpoint is blocked by CORS
Cross-Origin Request BlockedShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
The 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
The 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
The 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
Preflight returns 401 or 403 while normal calls with a token workHTTP API with a $default route and an authorizer rejects the preflightFix
- 1
What does the error look like?
Cross-Origin Request BlockedAccess-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 Handler2Fix
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
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_ID2Fix
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
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 CorsConfiguration2Fix
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
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 NONE3Verify
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
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:
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- RaheebA consumer app shipped to both stores from one Flutter codebase on a .NET and Azure back end.
Related fixes
Mobile apps
Flutter web request fails with a CORS error and Dart code cannot fix it
CORS preflight channel did not succeed
In a browser, the browser decides whether your Dart code may read a cross-origin response, and the server grants that with CORS headers.
4 causes, each with a fixMobile 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 fixMobile apps
Gradle cannot find com.google.firebase:firebase-analytics-ktx
Required by: project :app
Firebase moved the Kotlin extensions into the main modules and stopped releasing the -ktx modules in July 2025.
2 causes, each with a fixMobile apps
Gradle cannot create LibraryVariantBuilderImpl in a Flutter Android build
Could not create an instance of type com.android.build.api.variant.impl.LibraryVariantBuilderImpl
This error appears when the Android Gradle plugin (AGP) cannot run in the Gradle or IDE you use.
3 causes, each with a fixMobile apps
Flutter release build cannot open the keystore: HmacPBESHA256 not available
Algorithm HmacPBESHA256 not available
The keystore is a PKCS12 file protected by a newer algorithm than the Java that is reading it understands.
3 causes, each with a fixMobile apps
Android install error: the package conflicts with an existing package of the same name
The package conflicts with an existing package by the same name
Android allows only one app per application ID, and an update must be signed with the same certificate as the installed version.
3 causes, each with a fix