Maaz Zindani

Loading the index…

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

Flutter web request fails with a CORS error and Dart code cannot fix it

ErrorCORS header 'Access-Control-Allow-Origin' missing

Short 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.

  • Applies to Flutter 3.3x stable (web), package:http, Chrome and Firefox current
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1CORS header 'Access-Control-Allow-Origin' missing, and the curl output has no such headerThe server sends no Access-Control-Allow-Origin headerFix
    2. 2CORS preflight channel did not succeed, or missing token 'authorization' in Access-Control-Allow-HeadersThe preflight OPTIONS request is not answered correctlyFix
    3. 3Credential is not supported if the CORS header 'Access-Control-Allow-Origin' is '*'Cookies or credentials are sent while the server answers with *Fix
    4. 4API calls work, but Image.network pictures from a CDN do not render as expected on webOnly images from another site failFix

What does the error look like?

  • CORS header 'Access-Control-Allow-Origin' missing
  • CORS preflight channel did not succeed
  • missing 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: Origin

3Verify

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

Did this fix it?

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: 86400

3Verify

Repeat the preflight curl: the three Access-Control headers are present, then retry from the app.

flutter run -d chrome

Confirmed by developer.mozilla.org

Did this fix it?

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: Origin

3Verify

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

Did this fix it?

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 paths

3Verify

The curl output has the header, and the images load on web.

flutter run -d chrome

Confirmed by docs.flutter.dev

Did this fix it?

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:

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 fix

Next step

Want this handled for good?

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