Maaz Zindani

Loading the index…

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

Dio throws 'status code of 404 and RequestOptions.validateStatus' in Flutter

ErrorThis exception was thrown because the response has a status code of 404 and RequestOptions.validateStatus was configured to throw for this status code.

Short answer

Dio throws a DioException for any response outside 2xx and 304, and a 404 is one. The exception is not the bug: the server answered 404. Print e.response and requestOptions to see the final URL, fix the path, or accept 404 on purpose with validateStatus.

  • 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 and print what Dio sent and what the server answered. The request URI and the response body usually show the problem at once.

    try {
      await dio.get('/users/42');
    } on DioException catch (e) {
      print(e.requestOptions.uri);
      print(e.response?.statusCode);
      print(e.response?.data);
    }
  2. 2Match what you see, then jump to its fix

    1. 1requestOptions.uri differs from the endpoint you meantThe URL is wrong: path, base URL or trailing slashFix
    2. 2The server returns 404 on purpose, for example 'user not found', and the app crashes on itA 404 is a normal answer your code should handleFix
    3. 3e.response is null in the catch blockThe error is a missing response, not a 404Fix

What does the error look like?

  • This exception was thrown because the response has a status code of 404 and RequestOptions.validateStatus was configured to throw for this status code.

Cause 1 of 3

The URL is wrong: path, base URL or trailing slash

1Check

Compare the printed URI with the working URL from your API docs or a browser. Look for a missing path segment, a doubled slash or a base URL that already contains part of the path.

print(dio.options.baseUrl);
print(e.requestOptions.uri);

2Fix

Set baseUrl once, to the host and the fixed prefix, and give each call only the rest of the path.

final dio = Dio(BaseOptions(baseUrl: 'https://api.example.com/v1'));
final res = await dio.get('/users/42');

3Verify

The printed URI now matches the working URL and the status is 200.

print(res.statusCode);

Confirmed by pub.dev

Did this fix it?

Cause 2 of 3

A 404 is a normal answer your code should handle

1Check

Dio treats a response as a success only when validateStatus returns true for its code. The default rejects everything outside 2xx and 304.

print(e.response?.data);

2Fix

Handle the exception where you expect it, or accept the status for this one call with validateStatus.

final res = await dio.get(
  '/users/42',
  options: Options(
    validateStatus: (status) => status != null && status < 500,
  ),
);
if (res.statusCode == 404) {
  // show 'not found' in the UI
}

3Verify

The call returns a Response with statusCode 404 and no exception is thrown.

print(res.statusCode);

Confirmed by pub.dev

Did this fix it?

Cause 3 of 3

The error is a missing response, not a 404

1Check

The response can be null when the request cannot reach the HTTP server at all, so no status code exists.

print(e.response == null);
print(e.message);

2Fix

Treat it as a connection problem: check the host name, network and certificate rather than the route.

if (e.response == null) {
  print('No response: ${e.message}');
}

3Verify

With the host reachable, e.response holds a status code again.

print(e.response?.statusCode);

Confirmed by pub.dev

Did this fix it?

How do I stop it coming back?

  • Keep baseUrl in one place and log requestOptions.uri in a Dio interceptor while developing.
  • Wrap calls in a repository method that turns DioException into your own error types.
  • Use validateStatus per call, not globally, so real failures still throw.

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.