Flutter web request fails with a CORS error and Dart code cannot fix it
CORS header 'Access-Control-Allow-Origin' missingShort answer
In a browser, the browser decides whether your Dart code may read a cross-origin response, and the server grants that with CORS headers. Nothing you write in Dart can switch the check off. Read the browser console message, then fix the server's headers, or route the call through a server you control.
Fix it fast
1Find out which cause you have
Reproduce the request with curl, sending the origin your Flutter web app is served from, which the browser console shows. The response headers show what the server sends. Then do the same with a preflight if your app sends JSON or an Authorization header.
curl -i https://api.example.com/v1/items -H "Origin: http://localhost:5000"2Match what you see, then jump to its fix
- 1
CORS header 'Access-Control-Allow-Origin' missing, and the curl output has no such headerThe server sends no Access-Control-Allow-Origin headerFix - 2
CORS preflight channel did not succeed, or missing token 'authorization' in Access-Control-Allow-HeadersThe preflight OPTIONS request is not answered correctlyFix - 3
Credential is not supported if the CORS header 'Access-Control-Allow-Origin' is '*'Cookies or credentials are sent while the server answers with *Fix - 4
API calls work, but Image.network pictures from a CDN do not render as expected on webOnly images from another site failFix
- 1
What does the error look like?
CORS header 'Access-Control-Allow-Origin' missingCORS preflight channel did not succeedmissing token 'authorization' in CORS header 'Access-Control-Allow-Headers' from CORS preflight channel
Cause 1 of 4
The server sends no Access-Control-Allow-Origin header
1Check
MDN describes this header as the one that tells the browser which origin may read the response. If curl shows no Access-Control-Allow-Origin line, the server has not opted in.
curl -s -D - -o /dev/null https://api.example.com/v1/items -H "Origin: http://localhost:5000"2Fix
Make the API return the header for your app's origin (or * for a public resource that needs no credentials). This change is on the server or gateway. In Flutter you can only avoid the problem by calling a server you control.
Access-Control-Allow-Origin: https://app.example.com
Vary: Origin3Verify
Run the same curl and see the header; the browser console shows no CORS message.
curl -s -D - -o /dev/null https://api.example.com/v1/items -H "Origin: https://app.example.com"Confirmed by developer.mozilla.org
Cause 2 of 4
The preflight OPTIONS request is not answered correctly
1Check
A request with Content-Type application/json or an Authorization header is not a simple request, so the browser first sends OPTIONS. Send that same preflight by hand and read the answer.
curl -i -X OPTIONS https://api.example.com/v1/items \
-H "Origin: https://app.example.com" \
-H "Access-Control-Request-Method: POST" \
-H "Access-Control-Request-Headers: content-type,authorization"2Fix
Answer OPTIONS on that route with a success status and list the method and headers your app sends.
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 864003Verify
Repeat the preflight curl: the three Access-Control headers are present, then retry from the app.
flutter run -d chromeConfirmed by developer.mozilla.org
Cause 3 of 4
Cookies or credentials are sent while the server answers with *
1Check
On web, package:http's BrowserClient has a withCredentials switch that sends cookies and authorization headers across sites. MDN says that with credentials the server must not answer with the wildcard.
grep -rn 'withCredentials' lib/2Fix
Either stop sending credentials, or make the server return the exact origin together with Access-Control-Allow-Credentials: true, and list explicit headers and methods instead of *.
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin3Verify
The response carries the exact origin and the app can read the body.
curl -s -D - -o /dev/null https://api.example.com/v1/me -H "Origin: https://app.example.com"Confirmed by developer.mozilla.org
Cause 4 of 4
Only images from another site fail
1Check
Flutter's web renderer needs the raw bytes of an image, and that needs CORS headers from the image server; without them Flutter falls back to an HTML img element.
curl -s -D - -o /dev/null https://cdn.example.com/photo.jpg -H "Origin: https://app.example.com"2Fix
Serve the images from your own origin, or from a CDN configured to send Access-Control-Allow-Origin. If you cannot change that server, put a small proxy you control in front of it, as Flutter's page suggests.
// firebase.json (Firebase Hosting example from Flutter's page)
// set an Access-Control-Allow-Origin header on the image paths3Verify
The curl output has the header, and the images load on web.
flutter run -d chromeConfirmed by docs.flutter.dev
How do I stop it coming back?
- Decide the allowed origins on the server once, in an allowlist, and add the production domain before the first release.
- Test every new endpoint with curl and a preflight before wiring it into the Flutter app.
- Never send credentials from web unless you really need cookies; bearer tokens in an Authorization header need only the preflight rules.
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:
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
Related fixes
Web apps
The browser blocks your API response: no Access-Control-Allow-Origin header
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://api.example.com/orders. (Reason: CORS header 'Access-Control-Allow-Origin' missing).
The browser received the response but refused to hand it to your script, because it did not carry an Access-Control-Allow-Origin header naming the page's origin.
4 causes, each with a fixMobile apps
AudioCache has no play method after updating audioplayers
The method 'play' isn't defined for the type 'AudioCache'.
Since audioplayers 1.0, AudioCache only turns asset files into local files and caches them.
2 causes, each with a fixMobile apps
Flutter Bloc throws that emit was called after the event handler completed
emit was called after an event handler completed normally.
Each on<Event> handler gets its own Emitter, and it stops working the moment the handler's returned Future completes.
2 causes, each with a fixMobile apps
analysis_options.yaml: the URI it includes can't be found
include_file_not_found
The analyzer reports include_file_not_found when the file named after include: in analysis_options.yaml does not resolve.
2 causes, each with a fixMobile apps
Dart error: the body might complete normally and return null for a non-nullable type
body_might_complete_normally
Dart found a path through your function or callback that reaches the closing brace without a return.
3 causes, each with a fixMobile apps
Dart throws ConcurrentModificationError while looping over a list
ConcurrentModificationError
Dart throws this when a collection changes size while something iterates it.
2 causes, each with a fix