Dart throws 'List<dynamic> is not a subtype of type Map<String, dynamic>'
type 'List<dynamic>' is not a subtype of type 'Map<String, dynamic>' in type castShort 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.
Fix it fast
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));2Match what you see, then jump to its fix
- 1
The 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
It 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
A shared function such as T parse(String body) is used for list and object endpoints alikeA generic helper assumes every response is a MapFix
- 1
What does the error look like?
type 'List<dynamic>' is not a subtype of type 'Map<String, dynamic>' in type castError: 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 runConfirmed by docs.flutter.dev
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 testConfirmed by docs.flutter.dev
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 testConfirmed by api.dart.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
AudioCache has no play method after updating audioplayers
The method 'play' isn't defined for the type 'AudioCache'.
Since audioplayers 1.0, AudioCache only turns asset files into local files and caches them.
2 causes, each with a fixMobile apps
Flutter Bloc throws that emit was called after the event handler completed
emit was called after an event handler completed normally.
Each on<Event> handler gets its own Emitter, and it stops working the moment the handler's returned Future completes.
2 causes, each with a fixMobile apps
analysis_options.yaml: the URI it includes can't be found
include_file_not_found
The analyzer reports include_file_not_found when the file named after include: in analysis_options.yaml does not resolve.
2 causes, each with a fixMobile apps
Dart error: the body might complete normally and return null for a non-nullable type
body_might_complete_normally
Dart found a path through your function or callback that reaches the closing brace without a return.
3 causes, each with a fixMobile apps
Dart throws ConcurrentModificationError while looping over a list
ConcurrentModificationError
Dart throws this when a collection changes size while something iterates it.
2 causes, each with a fixMobile apps
Dart cannot turn a compact timestamp like 20201101153000 into a DateTime
FormatException: Invalid date format
DateTime.parse accepts a subset of ISO 8601, and a time part must be introduced by T or a space.
2 causes, each with a fix