JSON decoded to a Map but the code treats it as a List
Unhandled Exception: type 'InternalLinkedHashMap<String, dynamic>' is not a subtype of type 'List<dynamic>'Short answer
jsonDecode returns a Map for a JSON object and a List for a JSON array. This error means the response is an object but your code casts it to a list. Print the decoded value, then read the list under its key, or handle an object that holds an error message.
Fix it fast
1Find out which cause you have
Print what the server really sent before decoding, and see whether it starts with a bracket or a brace.
debugPrint(response.body); final decoded = jsonDecode(response.body); debugPrint(decoded.runtimeType.toString());2Match what you see, then jump to its fix
What does the error look like?
Unhandled Exception: type 'InternalLinkedHashMap<String, dynamic>' is not a subtype of type 'List<dynamic>'
Cause 1 of 2
The list is wrapped in an object
1Check
jsonDecode gives a Map for an object. A cast to List on that Map fails even though a list is inside it.
debugPrint((jsonDecode(response.body) as Map).keys.toString());2Fix
Cast to a Map first, then read the list under its key.
final body = jsonDecode(response.body) as Map<String, dynamic>;
final list = body['items'] as List<dynamic>;
final users = list
.map((e) => User.fromJson(e as Map<String, dynamic>))
.toList();3Verify
Reload the screen and check that the items appear.
flutter runConfirmed by docs.flutter.dev
Cause 2 of 2
The server answered with an error object instead of the array
1Check
Error bodies are usually objects, while the success body is an array, so the same code path sees both shapes.
debugPrint('${response.statusCode} ${response.body}');2Fix
Check the status code first, and test the type before you cast.
if (response.statusCode != 200) {
throw Exception('Request failed: ${response.statusCode}');
}
final decoded = jsonDecode(response.body);
if (decoded is! List) {
throw FormatException('Expected a JSON array, got ${decoded.runtimeType}');
}3Verify
Force an error response, for example with a wrong token, and read the clear exception.
flutter runConfirmed by api.dart.dev
How do I stop it coming back?
- Write the expected JSON shape next to the parsing code, as a comment or a model class.
- Log the status code and body in debug builds.
- Parse into typed models once, and keep casts in one place.
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
Dart throws 'List<dynamic> is not a subtype of type Map<String, dynamic>'
Error: List<dynamic> is not a subtype of type Map<String, dynamic>
jsonDecode returns a List<dynamic> for a JSON array and a Map<String, dynamic> for a JSON object.
3 causes, each with a fixMobile 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 fix