Maaz Zindani

Loading the index…

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

Dio requests fail with a connection or receive timeout in Flutter

ErrorDioException [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.

  • Applies to Flutter 3.35, Dart 3.9, dio 5.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1DioExceptionType.connectionTimeoutThe connection was not opened in timeFix
    2. 2DioExceptionType.receiveTimeoutThe server answered too slowly (receive timeout)Fix
    3. 3DioExceptionType.sendTimeoutA large upload runs out of send timeFix
    4. 4An unhandled DioException reaches the UI or the error zoneThe timeout is not handled in the calling codeFix

What does the error look like?

  • DioException [connection timeout]
  • DioExceptionType.connectionTimeout
  • DioExceptionType.receiveTimeout
  • DioExceptionType.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

Did this fix it?

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

Did this fix it?

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 DioException

Confirmed by pub.dev

Did this fix it?

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/ | head

2Fix

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 app

Confirmed by pub.dev

Did this fix it?

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:

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.