DEV Community

Chanpenh Yorn
Chanpenh Yorn

Posted on Edited on

Why your Flutter JSON model crashes at runtime (and how to generate one that doesn't)

You write a model, the first API response parses fine, and a week later a crash report says:

type 'int' is not a subtype of type 'double' in type cast
Enter fullscreen mode Exit fullscreen mode

Nothing in your code changed. The data did. Here are the three type errors I see most often with jsonDecode, why they happen, and how to write (or generate) models that survive real responses.

1. int vs double

Dart's jsonDecode reads the number type from the text. 1.0 is a double, 1 is an int:

import 'dart:convert';

void main() {
  final a = jsonDecode('{"price": 1.0}') as Map<String, dynamic>;
  print(a['price'].runtimeType); // double

  final b = jsonDecode('{"price": 1}') as Map<String, dynamic>;
  final price = b['price'] as double;
  // type 'int' is not a subtype of type 'double' in type cast
}
Enter fullscreen mode Exit fullscreen mode

Many backends drop the .0 for whole numbers, so a price of 3.0 arrives as 3. The safe cast for any field that is "a number with decimals" is:

final price = (json['price'] as num).toDouble();
Enter fullscreen mode Exit fullscreen mode

2. List<dynamic> vs List<String>

jsonDecode has no idea what your list should contain, so every JSON array becomes List<dynamic>:

final json = jsonDecode('{"tags": ["a", "b"]}') as Map<String, dynamic>;
final tags = json['tags'] as List<String>;
// type 'List<dynamic>' is not a subtype of type 'List<String>' in type cast
Enter fullscreen mode Exit fullscreen mode

Cast each item instead of the list:

final tags = (json['tags'] as List<dynamic>).map((e) => e as String).toList();
Enter fullscreen mode Exit fullscreen mode

Lists of objects work the same way, with fromJson on each item:

final items = (json['items'] as List<dynamic>)
    .map((e) => Item.fromJson(e as Map<String, dynamic>))
    .toList();
Enter fullscreen mode Exit fullscreen mode

3. The key that is only sometimes there

You build the model from one sample response. In that sample every item has a note. In production some items don't, and json['note'] as String throws because the value is null. Any key that can be missing or null needs a nullable type, String?, and a non-required constructor parameter.

The fix is to look at more than one sample. If a key is missing from any item, or null in any item, it's nullable.

A model that handles all three

Given this sample, where the second item has a note and the first doesn't:

{
  "id": 7,
  "price": 1.0,
  "tags": ["new"],
  "items": [
    { "sku": "A1", "qty": 2 },
    { "sku": "B2", "qty": 1, "note": "gift" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

a model that survives real responses looks like this:

class Order {
  final int id;
  final double price;
  final List<String> tags;
  final List<Item> items;

  const Order({
    required this.id,
    required this.price,
    required this.tags,
    required this.items,
  });

  factory Order.fromJson(Map<String, dynamic> json) => Order(
        id: json['id'] as int,
        price: (json['price'] as num).toDouble(),
        tags: (json['tags'] as List<dynamic>).map((e) => e as String).toList(),
        items: (json['items'] as List<dynamic>).map((e) => Item.fromJson(e as Map<String, dynamic>)).toList(),
      );

  Map<String, dynamic> toJson() => {
        'id': id,
        'price': price,
        'tags': tags,
        'items': items.map((e) => e.toJson()).toList(),
      };
}

class Item {
  final String sku;
  final int qty;
  final String? note;

  const Item({
    required this.sku,
    required this.qty,
    this.note,
  });

  factory Item.fromJson(Map<String, dynamic> json) => Item(
        sku: json['sku'] as String,
        qty: json['qty'] as int,
        note: json['note'] as String?,
      );

  Map<String, dynamic> toJson() => {
        'sku': sku,
        'qty': qty,
        'note': note,
      };
}
Enter fullscreen mode Exit fullscreen mode

Decoding {"id": 8, "price": 3, "tags": [], "items": [{"sku": "C3", "qty": 1}]} with it gives price = 3.0 and note = null, with no exceptions.

Generating it

I wrote that model by hand far too many times, so I built a free JSON to Dart generator (disclosure: it's my project). The model above is its actual output for the sample. It:

  • runs entirely in the browser, so API responses are never uploaded,
  • reads number types from the raw text, so 1.0 stays a double (JavaScript's JSON.parse would turn it into 1),
  • merges the keys of every item in an array and makes keys that are missing or null in some items nullable,
  • outputs plain Dart (no packages), json_serializable or freezed,
  • can repair a map printed by print() / debugPrint (like {id: 1, name: Ada}) into JSON first.

It does not guess DateTime or enums; dates stay String, so convert those by hand.

If you're debugging one of these errors right now, the guide Flutter JSON Errors: "is not a subtype" Explained covers more of them, including '_Map<String, dynamic>' is not a subtype of type ....

Top comments (6)

Collapse
 
ahmedznouda profile image
Ahmed ZNOUDA •

Good list. One trap with the int/double case: on Flutter web you never see it. Compiled to JavaScript, every number is a JS number, so 1 as double succeeds and 1.0 is int is true. A model can pass all its tests in Chrome and then crash on Android with the exact error at the top of your post, so it's worth running the fromJson tests on the VM with plain flutter test too. The same JS number issue rounds IDs above 2^53 on web, one more reason to ask the backend for string IDs.

For JSON files we bundle ourselves, one unit test loads every asset file and parses it through the real model class. A typo in a data file fails CI instead of crashing on someone's phone.

Collapse
 
chanpenh profile image
Chanpenh Yorn •

Great point, and I checked it: compiled to JS, 1 as double succeeds and 1.0 is int is true, while the VM throws. An ID of 9007199254740993 also comes back as ...992 on web. So "it works in Chrome" proves nothing about Android. Running the fromJson tests with plain flutter test (VM by default) is the right call, and string IDs avoid the rounding entirely. I like the asset test too: parsing every bundled JSON file through the real model in CI is cheap and catches typos early.

Collapse
 
ahmedznouda profile image
Ahmed ZNOUDA •

Thanks for running it, the 9007199254740993 coming back as ...992 makes it concrete. If the app also ships to web, adding a second CI run with flutter test --platform chrome covers the other side: the same tests compiled to JS, so a model test with an ID above 2^53 fails there instead of in production. For pure model tests it's a cheap extra run.

Thread Thread
 
chanpenh profile image
Chanpenh Yorn •

Thanks, that's a good addition. Running the same model tests a second time with flutter test --platform chrome costs one extra CI job and catches the web-only behaviour, like the rounded ID, before users do. Between the VM run and the Chrome run, both sides of the number handling are covered.

Collapse
 
lycore profile image
Lycore Development •

The int vs double one bites almost everyone once, and the (x as num).toDouble() pattern is the right fix. One more runtime surprise we see is IDs or timestamps arriving as either a string or a number depending on the endpoint version. A small tolerant parse helper for those fields, plus a test that runs fromJson against a few saved real responses (including ones with nulls and missing keys), catches most of these before release. Do you prefer json_serializable with custom converters for that, or hand-written parsing?

Collapse
 
chanpenh profile image
Chanpenh Yorn •

Thanks! The string-or-number ID is a good one to add. I keep json_serializable for the model and put the tolerance in a small function on just that field:

int intFromStringOrNum(Object? value) => switch (value) {
      int v => v,
      String v => int.parse(v),
      _ => throw FormatException('Expected an int or a numeric string', value),
    };

@JsonKey(fromJson: intFromStringOrNum)
final int id;
Enter fullscreen mode Exit fullscreen mode

The rest of the generated code stays strict, so anything unexpected still fails loudly. And +1 on running fromJson against saved real responses, including ones with nulls and missing keys. That catches far more than a single sample.