Maaz Zindani

Loading the index…

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

Setting a timeout on an HTTP request in Flutter and Dart

ErrorTimeoutException

Short answer

Dart HTTP calls have no timeout of their own beyond the operating system's. Add .timeout(Duration(...)) to the request future and catch TimeoutException, set connectionTimeout on an HttpClient, or set connectTimeout and receiveTimeout in Dio. Note that Future.timeout does not cancel the request.

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

Fix it fast

  1. 1Find out which cause you have

    Find which client your code uses, because each one sets its timeout differently.

    grep -rn "http.get\|HttpClient()\|Dio(" lib/
  2. 2Match what you see, then jump to its fix

    1. 1The screen shows a spinner for minutes and no error appearsThe request future has no time limitFix
    2. 2SocketException while connecting to a host that is downdart:io HttpClient waits on a dead hostFix
    3. 3DioException of type receiveTimeout, or none at all because nothing is setDio is used with no timeouts setFix

What does the error look like?

  • TimeoutException
  • SocketException
  • DioException with type receiveTimeout

Cause 1 of 3

The request future has no time limit

1Check

A plain request waits as long as the system lets it.

grep -rn "await http\." lib/

2Fix

Chain .timeout on the future and catch TimeoutException. Without onTimeout the future completes with that exception. The original request is not cancelled; its late result is ignored.

import 'dart:async';
import 'package:http/http.dart' as http;

try {
  final res = await http
      .get(Uri.parse('https://example.com/api'))
      .timeout(const Duration(seconds: 10));
  // use res
} on TimeoutException {
  // show a retry message
}

3Verify

Point the URL at a server that does not answer. The catch block runs after 10 seconds.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 2 of 3

dart:io HttpClient waits on a dead host

1Check

connectionTimeout is null by default, so the operating system's own limit applies. It only affects new connections made after it is set.

grep -rn "HttpClient()" lib/

2Fix

Set connectionTimeout when you create the client. A SocketException is thrown when it passes. Combine it with Future.timeout for slow responses.

final client = HttpClient()
  ..connectionTimeout = const Duration(seconds: 5);

3Verify

Request an address that does not answer and count the seconds until the error.

flutter run

Confirmed by api.flutter.dev

Did this fix it?

Cause 3 of 3

Dio is used with no timeouts set

1Check

Dio has its own timeouts on BaseOptions. receiveTimeout and sendTimeout throw a DioException of the matching type.

grep -rn "BaseOptions" lib/

2Fix

Set the timeouts once on the shared instance and catch DioException.

final dio = Dio(BaseOptions(
  baseUrl: 'https://example.com',
  connectTimeout: const Duration(seconds: 5),
  receiveTimeout: const Duration(seconds: 3),
));

try {
  await dio.get('/api');
} on DioException catch (e) {
  if (e.type == DioExceptionType.receiveTimeout) {
    // show a retry message
  }
}

3Verify

Call a slow endpoint and see the catch branch run.

flutter run

Confirmed by pub.dev

Did this fix it?

How do I stop it coming back?

  • Give every network call a limit, set in one shared client.
  • Show a retry button instead of a spinner without end.
  • Remember Future.timeout stops waiting but leaves the request running.

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.