Dio POST request ignores the headers you set
The server says the Authorization header is missing on a POSTShort 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.
Fix it fast
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());2Match what you see, then jump to its fix
- 1
The header is missing from the logged request headersThe header is not in Options or BaseOptionsFix - 2
The server wants form fields but receives JSON, or the reverseThe body type decides the Content-TypeFix - 3
Works 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
- 1
What does the error look like?
The server says the Authorization header is missing on a POSTThe 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 runConfirmed by pub.dev
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 runConfirmed by pub.dev
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 chrome2Fix
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-Type3Verify
Repeat the POST in Chrome; the preflight succeeds.
flutter run -d chromeConfirmed by pub.dev
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:
- 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.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
A Dio request in Flutter fails with HTTP 405 Method Not Allowed
405 Method Not Allowed
405 means the server knows the URL but not the HTTP method you used on it.
2 causes, each with a fixMobile apps
Dio throws 'status code of 404 and RequestOptions.validateStatus' in Flutter
This exception was thrown because the response has a status code of 404 and RequestOptions.validateStatus was configured to throw for this status code.
Dio throws a DioException for any response outside 2xx and 304, and a 404 is one.
3 causes, each with a fixMobile apps
Dio requests fail with a connection or receive timeout in Flutter
DioExceptionType.connectionTimeout
Dio throws a DioException whose type says which timer ran out: connectionTimeout, sendTimeout or receiveTimeout.
4 causes, each with a fixMobile apps
Dio interceptor throws: the handler has already been called
Bad state: Future already completed
In Dio every interceptor callback gets a handler, and that handler may be completed only once.
2 causes, each with a fixMobile apps
Flutter Dio throws a bad response error with status 422
Unhandled Exception: DioError [DioErrorType.response]: Http status error [422]
A 422 is not a Dio fault.
3 causes, each with a fixMobile apps
Setting a timeout on an HTTP request in Flutter and Dart
SocketException
Dart HTTP calls have no timeout of their own beyond the operating system's.
3 causes, each with a fix