How to fix "FormatException: Unexpected character error" in Flutter

If you use Flutter and Dart, you’ve probably come across some confusing error messages. One of the most common is:

Unhandled Exception: FormatException: Unexpected character ...

If you’re working with APIs or parsing JSON in Flutter, chances are you’ve run into this error at least once. In this blog, we’ll break down what this error means, why it happens, and how you can fix it—sharing our own debugging approach and best practices along the way.

What does “Unhandled Exception: FormatException: Unexpected character …” mean?

This error usually pops up when you try to parse a JSON response, but the data you’re trying to decode isn’t valid JSON. It could be an HTML error page, a plain string, or just malformed JSON. Dart’s jsonDecode expects a valid JSON string, and anything else will trigger this exception.

Why does it happen?

• The API response is not in JSON format (e.g., HTML error page, plain text, etc.)
• You’re decoding the wrong property (e.g., using response.toString() instead of response.body)
• The server returned an error or unexpected data
• There’s a typo or syntax error in the JSON

How to debug and solve it

Here’s our step-by-step approach:

1. Print the raw response

   Before decoding, print the response to see what you’re actually getting:

   print(response.body);

2. Check your decoding logic

   A common mistake is to decode response.toString() instead of response.body. Make sure you’re decoding the actual response body:

   // ❌ Incorrect
   String jsonsDataString = response.toString();
   _data = jsonDecode(jsonsDataString);
   
   // ✅ Correct
   String jsonsDataString = response.body.toString();
   _data = jsonDecode(jsonsDataString);

3. Use try-catch blocks

   Always wrap your decoding logic in a try-catch to handle unexpected data gracefully:

   try {
     final data = jsonDecode(response.body);
     // Use your data
   } catch (e) {
     print('JSON parsing error: $e');
     // Handle the error or show a user-friendly message
   }

4. Validate your API responses

   Sometimes, the backend might return an error message or HTML instead of JSON. Always check the status code before decoding:

   if (response.statusCode == 200) {
     // Safe to decode
     final data = jsonDecode(response.body);
   } else {
     print('API error: ${response.statusCode}');
     print(response.body);
   }

Real-World Example

Let’s say you’re fetching data from an API and get this error. Here’s how you can fix it:

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

Future<void> fetchData() async {
  final response = await http.get(Uri.parse('https://api.example.com/data'));
  if (response.statusCode == 200) {
    try {
      final data = jsonDecode(response.body);
      print(data);
    } catch (e) {
      print('JSON parsing error: $e');
    }
  } else {
    print('API error: ${response.statusCode}');
    print(response.body);
  }
}

Conclusion

The “Unhandled Exception: FormatException: Unexpected character …” error in Flutter is common, but with the right debugging steps, it’s easy to resolve. Always check your API responses, decode the correct property, and use error handling to make your app resilient. If you’re stuck, print everything and don’t hesitate to ask for help—the Flutter community is always there!

Need help with Flutter errors or cross-platform development? Let’s talk!

Click the button below to book a free consultation with us 🤝

Book Free Consultation