Maaz Zindani

Loading the index…

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

Dart throws 'List<dynamic> is not a subtype of type Map<String, dynamic>'

Errortype 'List<dynamic>' is not a subtype of type 'Map<String, dynamic>' in type cast

Short answer

jsonDecode returns a List<dynamic> for a JSON array and a Map<String, dynamic> for a JSON object. The error means your code cast an array to a map. Print the decoded type, then either decode as a list and convert every item, or read the list from the key that holds it.

  • Applies to Dart 3.6 and newer, Flutter 3.3x stable
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the runtime type and the first characters of the response. A body starting with [ is an array; one starting with { is an object.

    final decoded = jsonDecode(response.body);
    print(decoded.runtimeType);
    print(response.body.substring(0, 80));
  2. 2Match what you see, then jump to its fix

    1. 1The body starts with [ and the stack trace points at a cast to Map<String, dynamic>The endpoint returns an array and the code expects one objectFix
    2. 2It works for some requests and fails for others, for example one result versus manyThe same endpoint returns an object in one case and an array in anotherFix
    3. 3A shared function such as T parse(String body) is used for list and object endpoints alikeA generic helper assumes every response is a MapFix

What does the error look like?

  • type 'List<dynamic>' is not a subtype of type 'Map<String, dynamic>' in type cast
  • Error: List<dynamic> is not a subtype of type Map<String, dynamic>

Cause 1 of 3

The endpoint returns an array and the code expects one object

1Check

Look for jsonDecode(body) as Map<String, dynamic> or a fromJson(jsonDecode(body)) call on a list endpoint.

grep -rn "as Map<String, dynamic>" lib/

2Fix

Cast to List<dynamic> first, then convert each element with your fromJson constructor.

final decoded = jsonDecode(body) as List<dynamic>;
final users = decoded
    .map((e) => User.fromJson(e as Map<String, dynamic>))
    .toList();

3Verify

The screen shows the list and the cast error is gone.

flutter run

Confirmed by docs.flutter.dev

Did this fix it?

Cause 2 of 3

The same endpoint returns an object in one case and an array in another

1Check

Log the type for a few different requests. A single decoded value can be either shape.

print(jsonDecode(body).runtimeType);

2Fix

Check the runtime type with is before casting, and handle both shapes.

final decoded = jsonDecode(body);
if (decoded is List) {
  final users = decoded
      .map((e) => User.fromJson(e as Map<String, dynamic>))
      .toList();
} else if (decoded is Map<String, dynamic>) {
  final user = User.fromJson(decoded);
}

3Verify

Call the endpoint with a request that returns one item and one that returns many.

flutter test

Confirmed by docs.flutter.dev

Did this fix it?

Cause 3 of 3

A generic helper assumes every response is a Map

1Check

jsonDecode is declared to return dynamic, so the compiler does not warn you; the types are only known at runtime.

grep -rn "jsonDecode" lib/

2Fix

Give list endpoints their own parse step that casts to List<dynamic>, or use .cast<Map<String, dynamic>>() on the list.

final users = (jsonDecode(body) as List<dynamic>)
    .cast<Map<String, dynamic>>()
    .map(User.fromJson)
    .toList();

3Verify

Run the code path for both an object and a list endpoint.

flutter test

Confirmed by api.dart.dev

Did this fix it?

How do I stop it coming back?

  • Write down the shape of each endpoint (object or array) next to the model class.
  • Prefer json_serializable for larger projects, so field typos fail at compile time.
  • Add a test with a sample body for every endpoint you parse.

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.