Maaz Zindani

Loading the index…

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

Dio POST request ignores the headers you set

ErrorThe server says the Authorization header is missing on a POST

Short answer

Headers belong in Options for one request or in BaseOptions for the whole Dio instance, never in the data map. A POST also gets a Content-Type from its body: a Map is sent as JSON and FormData as multipart. Set contentType explicitly if the server expects form-urlencoded. On Flutter Web, custom headers trigger a CORS preflight.

  • Applies to Dio 5, Flutter 3.35, Dart 3.9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Log what Dio is really sending, so you compare it to what the server expects.

    dio.interceptors.add(LogInterceptor());
  2. 2Match what you see, then jump to its fix

    1. 1The header is missing from the logged request headersThe header is not in Options or BaseOptionsFix
    2. 2The server wants form fields but receives JSON, or the reverseThe body type decides the Content-TypeFix
    3. 3Works on Android and iOS, fails only in Chrome, with a CORS error in the browser consoleFlutter Web: the browser blocks the custom header (CORS preflight)Fix

What does the error look like?

  • The server says the Authorization header is missing on a POST
  • The server rejects the body because Content-Type is application/json, not application/x-www-form-urlencoded

Cause 1 of 3

The header is not in Options or BaseOptions

1Check

Options applies to one request and BaseOptions sets defaults on the Dio instance; the two are merged when the request is made. A header put inside the data map goes into the body instead.

grep -rn "dio.post" lib/

2Fix

Put the header in the headers map of Options, or in BaseOptions for every request.

final dio = Dio(BaseOptions(headers: {'Authorization': 'Bearer $token'}));

await dio.post(
  '/orders',
  data: {'id': 5},
  options: Options(headers: {'X-Client': 'mobile'}),
);

3Verify

The log now lists both headers.

flutter run

Confirmed by pub.dev

Did this fix it?

Cause 2 of 3

The body type decides the Content-Type

1Check

Dio serializes request data, except String, to JSON by default. FormData is sent as multipart/form-data.

grep -rn "FormData\|contentType" lib/

2Fix

Set contentType for that request, or on the instance, to match the server.

dio.post(
  '/info',
  data: {'id': 5},
  options: Options(contentType: Headers.formUrlEncodedContentType),
);

3Verify

The logged request shows the new content type.

flutter run

Confirmed by pub.dev

Did this fix it?

Cause 3 of 3

Flutter Web: the browser blocks the custom header (CORS preflight)

1Check

A request that is not a simple request triggers a preflight. Adding a custom header such as Authorization makes it one.

flutter run -d chrome

2Fix

Make the server answer the preflight by allowing your origin and the header, or add CORS middleware to your server. Browsers do not let client code skip this.

# server response must allow the request header, for example:
Access-Control-Allow-Headers: Authorization, Content-Type

3Verify

Repeat the POST in Chrome; the preflight succeeds.

flutter run -d chrome

Confirmed by pub.dev

Did this fix it?

How do I stop it coming back?

  • Create one Dio instance with BaseOptions for shared headers such as Authorization.
  • Keep LogInterceptor on in debug builds so the real headers are visible.
  • Test web builds against the real server early, because CORS never shows on mobile.

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

Next step

Want this handled for good?

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