fix(dio): prevent request hang when async interceptor throws

[ersanKolay]

Summary

Fixes #2138.

When an interceptor overrides onRequest/onResponse/onError with an async implementation and throws after an await without calling the handler, the request hangs indefinitely. The handler's Completer is never completed because:

1. The callback typedef is void, so the returned Future is discarded
2. The unhandled async error goes to the zone's uncaught error handler
3. Nobody ever calls handler.next()/reject()/resolve()

// This hangs forever:
class MyInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
    await refreshToken(); // throws
    handler.next(options); // never reached
  }
}

Approach

Each interceptor callback is now invoked inside a forked Zone with a custom handleUncaughtError. When an uncaught async error occurs and the handler hasn't been completed yet, the zone handler calls handler.reject() (or handler.next() for error interceptors) to unblock the request.

This approach differs from the reverted PR #2139 which changed the callback typedefs to FutureOr<void> and awaited the return value. That changed the microtask ordering and broke multi-interceptor chains (#2167). Zone.fork() does not await the callback -- it only catches async errors that would otherwise be lost, preserving the original execution order.

Why this works

Scenario	Before	After
Sync interceptor, calls handler	Works	Works (no change)
Sync interceptor, throws	Works (propagates via Future)	Works (sync errors pass through Zone.run)
Async interceptor, calls handler	Works	Works (zone has no effect)
Async interceptor, throws	Hangs forever	Zone catches error, rejects handler
Duplicate handler.next() calls	Throws StateError	Throws StateError (sync, passes through)

Test plan

• Added 3 new tests for async throw scenarios (onRequest, onResponse, onError)
• All 218 existing tests pass
• All 32 interceptor-specific tests pass (including "duplicate handler calls" and the existing "Caught exceptions before handler called" test)
• dart format and dart analyze clean

[AlexV525]

Sorry I accidently hit the close button.

This looks cool! I shall try to play it locally somehow...

[github-actions]

Code Coverage Report: Only Changed Files listed

Package	Base Coverage	New Coverage	Difference
dio/lib/src/dio_mixin.dart	🟢 94.14%	🟢 94.47%	🟢 0.33%
dio/lib/src/interceptor.dart	🟢 98.6%	🟢 99.3%	🟢 0.7%
Overall Coverage	🟢 88.44%	🟢 88.58%	🟢 0.14%

Minimum allowed coverage is 0%, this run produced 88.58%

[Copilot]

Pull request overview

This PR fixes a Dio request hang that occurs when an interceptor callback is implemented as async and throws after an await without completing its handler, by ensuring the handler is completed on uncaught async errors.

Changes:

• Run each interceptor callback inside a forked Zone that converts uncaught async errors into handler.reject()/handler.next() to unblock the request.
• Add new interceptor tests covering async-throw scenarios for onRequest, onResponse, and onError.
• Update the CHANGELOG.md with the fix description.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
dio/lib/src/dio_mixin.dart	Wraps interceptor callback execution in a forked Zone to catch uncaught async errors and complete the handler to prevent hangs.
dio/test/interceptor_test.dart	Adds regression tests ensuring async interceptor throws do not hang requests.
dio/CHANGELOG.md	Notes the fix in the Unreleased section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

handleUncaughtError receives a stackTrace but it’s currently ignored, so the DioException created via assureDioException will use requestOptions.sourceStackTrace/StackTrace.current instead of the interceptor’s actual throw site. Please thread the provided stackTrace into the error you pass to the handler (e.g., by constructing a DioException with stackTrace: stackTrace, or by extending assureDioException to accept a stack trace) so users get actionable traces.

[Copilot]

The custom handleUncaughtError swallows async errors when handler.isCompleted is already true (it neither forwards to parent.handleUncaughtError nor rethrows). That can hide genuinely unhandled errors from interceptor code that happen after calling the handler (e.g., fire-and-forget futures). Consider delegating to parent.handleUncaughtError(...) when the handler is already completed so those errors are still reported, while only converting to handler.reject/next when it isn’t completed yet.

Suggested change

	onUncaughtError(error);
	onUncaughtError(error);
	} else {
	parent.handleUncaughtError(zone, error, stackTrace);

[Copilot]

The Future.delayed(const Duration(milliseconds: 10)) is only used to force an async gap; using Duration.zero (or Future<void>.value()/Future<void>.microtask) would keep the test intent while avoiding unnecessary wall-clock delay in the suite.

[Copilot]

The Future.delayed(const Duration(milliseconds: 10)) is only used to force an async gap; using Duration.zero (or Future<void>.value()/Future<void>.microtask) would keep the test intent while avoiding unnecessary wall-clock delay in the suite.

[Copilot]

The Future.delayed(const Duration(milliseconds: 10)) is only used to force an async gap; using Duration.zero (or Future<void>.value()/Future<void>.microtask) would keep the test intent while avoiding unnecessary wall-clock delay in the suite.