Dio interceptor throws: the handler has already been called
Bad state: The handler has already been called, make sure each handler gets called only once.Short answer
In Dio every interceptor callback gets a handler, and that handler may be completed only once. Calling next, resolve or reject a second time on the same handler throws a StateError. Older Dio versions word it as Bad state: Future already completed. Make every code path in the callback end in exactly one handler call.
Fix it fast
1Find out which cause you have
Open the interceptor named in the stack trace and count the handler calls on each path through onRequest, onResponse and onError. More than one on a path is the bug.
grep -rn "handler\.\(next\|resolve\|reject\)" lib/2Match what you see, then jump to its fix
What does the error look like?
Bad state: The handler has already been called, make sure each handler gets called only once.Bad state: Future already completed
Cause 1 of 2
A branch calls the handler and then falls through to another call
1Check
Look for an if block that calls handler.reject or handler.resolve without a return, followed by handler.next at the bottom of the method.
grep -n "handler\." lib/network/auth_interceptor.dart2Fix
Return right after the handler call in the early branch, so the final call runs only when no earlier branch completed the handler.
@override
void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
if (token == null) {
return handler.reject(
DioException(requestOptions: options, message: 'No token'),
);
}
options.headers['Authorization'] = 'Bearer $token';
handler.next(options);
}3Verify
Send the request that failed; each request now finishes once, with no StateError.
flutter runConfirmed by raw.githubusercontent.com
Cause 2 of 2
Both a then block and a catch block, or a retry, complete the same handler
1Check
In onError, a retry through dio.fetch is often chained with then and catchError, or followed by a handler.next(err) that also runs. The success path and the failure path must not both call the handler.
grep -n "onError" -A20 lib/network/auth_interceptor.dart2Fix
Await the retry in a try block, resolve the handler with the new response, and call reject only in the catch block.
@override
Future<void> onError(DioException err, ErrorInterceptorHandler handler) async {
try {
final response = await dio.fetch(err.requestOptions);
handler.resolve(response);
} on DioException catch (e) {
handler.reject(e);
}
}3Verify
Force a failing request and watch it end in one resolve or one reject.
flutter runConfirmed by pub.dev
How do I stop it coming back?
- End every interceptor method path with exactly one of next, resolve or reject.
- Use return before a handler call inside an if, or use if and else.
- Prefer async and await with try and catch over long then chains in interceptors.
- Use QueuedInterceptor when requests must pass through one at a time, for example while refreshing a token.
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
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
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 POST request ignores the headers you set
The server rejects the body because Content-Type is application/json, not application/x-www-form-urlencoded
Headers belong in Options for one request or in BaseOptions for the whole Dio instance, never in the data map.
3 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