Maaz Zindani

Loading the index…

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

Flutter jsonDecode fails with FormatException on an HTTP response

ErrorUnhandled Exception: FormatException: Unexpected character (at character 1)

Short answer

jsonDecode only parses JSON text. The exception means the string you gave it is not JSON. Either you passed the Response object instead of response.body, or the server sent something else, such as an HTML error page. Print the status code and the start of the body, then fix whichever one is wrong.

  • Applies to Flutter 3.3x stable, Dart 3.x, package:http 1.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print what jsonDecode actually receives. The first characters of the body show whether it is JSON, HTML, or not a body at all.

    final response = await http.get(Uri.parse('https://api.example.com/items'));
    print(response.statusCode);
    print(response.headers['content-type']);
    print(response.body.substring(0, response.body.length.clamp(0, 200)));
  2. 2Match what you see, then jump to its fix

    1. 1The error message shows Instance of 'Response' as the source textThe Response object is decoded instead of its bodyFix
    2. 2The text after the error starts with < (an HTML page), or the body is emptyThe server did not return JSONFix

What does the error look like?

  • Unhandled Exception: FormatException: Unexpected character (at character 1)
  • Instance of 'Response'
  • FormatException: Unexpected character (at character 1) <!DOCTYPE html>

Cause 1 of 2

The Response object is decoded instead of its body

1Check

Search for the jsonDecode call and look at its argument. A Response is an object, not text. If the argument is the response variable itself, or a string built from it, the parser sees the object's default description and stops at character 1.

grep -rn "jsonDecode(" lib/

2Fix

Decode the body property, as the Flutter networking recipe does, and cast the result to the shape you expect.

import 'dart:convert';

final data = jsonDecode(response.body) as Map<String, dynamic>;

3Verify

Run the request again. The exception disappears and data holds your map.

print(data.keys);

Confirmed by docs.flutter.dev

Did this fix it?

Cause 2 of 2

The server did not return JSON

1Check

Compare the status code and the content-type header from the first step. An error page from the server, a login redirect or a wrong URL returns a body that is not JSON, and FormatException carries that text as its source.

try {
  jsonDecode(response.body);
} on FormatException catch (e) {
  print(e.message);
  print(e.offset);
  print(e.source);
}

2Fix

Check the status code before parsing, as the Flutter recipe does, and ask for JSON with an Accept header. Then correct the URL or the request until the server answers with 200 and a JSON body.

final response = await http.get(
  Uri.parse('https://api.example.com/items'),
  headers: {'Accept': 'application/json'},
);
if (response.statusCode == 200) {
  final data = jsonDecode(response.body);
} else {
  throw Exception('Request failed: ${response.statusCode}');
}

3Verify

The failing call now either returns parsed data or throws a clear status-code exception instead of a FormatException.

print(response.statusCode);

Confirmed by docs.flutter.dev

Did this fix it?

How do I stop it coming back?

  • Always parse response.body, never the response variable.
  • Check statusCode before decoding, and throw a clear error for anything that is not a success.
  • Send an Accept: application/json header on JSON endpoints.
  • Catch FormatException around decoding and log its source and offset while developing.

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.