Maaz Zindani

Loading the index…

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

Dio interceptor throws: the handler has already been called

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

  • Applies to Dio 5, Dart 3, Flutter 3.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1The error appears only on one kind of response or error, such as a 401A branch calls the handler and then falls through to another callFix
    2. 2The error follows a retry or refresh-token call made inside onErrorBoth a then block and a catch block, or a retry, complete the same handlerFix

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

2Fix

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 run

Confirmed by raw.githubusercontent.com

Did this fix it?

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

2Fix

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 run

Confirmed by pub.dev

Did this fix it?

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:

Related fixes

Mobile 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 fix

Next step

Want this handled for good?

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