Dio requests fail with a connection or receive timeout in Flutter
DioException [connection timeout]Short answer
Dio throws a DioException whose type says which timer ran out: connectionTimeout, sendTimeout or receiveTimeout. Print e.type first. Then set the matching Duration on BaseOptions or on that one request, and catch the type in your own code so the user sees a clear message instead of a crash.
Fix it fast
1Find out which cause you have
Catch the exception once and print its type. The type tells you which of the causes below applies.
try { await dio.get('https://example.com/api/items'); } on DioException catch (e) { print(e.type); // connectionTimeout, sendTimeout, receiveTimeout ... print(e.message); }2Match what you see, then jump to its fix
- 1
DioExceptionType.connectionTimeoutThe connection was not opened in timeFix - 2
DioExceptionType.receiveTimeoutThe server answered too slowly (receive timeout)Fix - 3
DioExceptionType.sendTimeoutA large upload runs out of send timeFix - 4
An unhandled DioException reaches the UI or the error zoneThe timeout is not handled in the calling codeFix
- 1
What does the error look like?
DioException [connection timeout]DioExceptionType.connectionTimeoutDioExceptionType.receiveTimeoutDioExceptionType.sendTimeout
Cause 1 of 4
The connection was not opened in time
1Check
This type is documented as caused by a connection timeout. Look at the connectTimeout you set and at whether the host is reachable at all from the device.
print(dio.options.connectTimeout);
print(dio.options.baseUrl);2Fix
Give the connection a realistic limit on BaseOptions, and make sure the base URL is an address the device can reach.
final dio = Dio(BaseOptions(
baseUrl: 'https://example.com',
connectTimeout: const Duration(seconds: 10),
));3Verify
Repeat the request on the same network and confirm the exception no longer appears.
final res = await dio.get('/api/items');
print(res.statusCode);Confirmed by pub.dev
Cause 2 of 4
The server answered too slowly (receive timeout)
1Check
In Dio, receiveTimeout limits the wait before the first response bytes arrive and also each gap between data events while the body downloads. It is not a cap on the total download time. A slow endpoint or a very short value trips it.
print(dio.options.receiveTimeout);2Fix
Raise receiveTimeout for the slow endpoint only, using per-request Options, instead of raising it for the whole app. A null or zero Duration means no limit.
final res = await dio.get(
'/api/report',
options: Options(receiveTimeout: const Duration(seconds: 60)),
);3Verify
Call the slow endpoint again and confirm a normal response arrives.
print(res.statusCode);Confirmed by pub.dev
Cause 3 of 4
A large upload runs out of send time
1Check
sendTimeout limits the time spent sending data. Large uploads on a slow mobile link can pass the limit even though the server is healthy.
print(dio.options.sendTimeout);2Fix
Set a larger sendTimeout on the upload request.
await dio.post(
'/api/upload',
data: formData,
options: Options(sendTimeout: const Duration(minutes: 2)),
);3Verify
Upload the same file again on the same connection.
// the call completes without a DioExceptionConfirmed by pub.dev
Cause 4 of 4
The timeout is not handled in the calling code
1Check
DioException has a type field. A plain catch (e) hides which timer fired, so every failure looks the same.
grep -rn "catch (e)" lib/ | head2Fix
Catch DioException and switch on its type, so each timeout gets its own message or retry.
try {
await dio.get('/api/items');
} on DioException catch (e) {
switch (e.type) {
case DioExceptionType.connectionTimeout:
case DioExceptionType.sendTimeout:
case DioExceptionType.receiveTimeout:
showMessage('The server took too long. Try again.');
default:
rethrow;
}
}3Verify
Turn on airplane mode, run the call and check that your message appears.
// manual check in the appConfirmed by pub.dev
How do I stop it coming back?
- Set connectTimeout and receiveTimeout once on BaseOptions, and override them only for the few slow endpoints.
- Catch DioException by type, not with a bare catch.
- Keep the base URL in one place so every request uses an address the device can reach.
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
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 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 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
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 fix