Maaz Zindani

Loading the index…

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

JSON decoded to a Map but the code treats it as a List

ErrorUnhandled 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.

  • Applies to Dart 3.x, Flutter 3.x, package:http
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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());
  2. 2Match what you see, then jump to its fix

    1. 1The body starts with { and has a key such as data, items or results holding the arrayThe list is wrapped in an objectFix
    2. 2The failing request returns a message or error key, often with a 4xx or 5xx statusThe server answered with an error object instead of the arrayFix

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 run

Confirmed by docs.flutter.dev

Did this fix it?

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 run

Confirmed by api.dart.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.