When API Response Types Don't Match Your Flutter Model

Syed Zubyl N — Thu, 05 Mar 2026 00:00:00 +0000

The Problem</h3>

A Flutter application was crashing on the profile screen with a cryptic error in the console:</p>

type 'int' is not a subtype of type 'bool?'</span></span></code></pre>
The app compiled perfectly, the API returned a 200 OK, but the JSON deserialization failed entirely, resulting in a red screen of death in debug mode (and a blank screen in production).</p>
Context</h3>
In Dart, type safety is strict. When you parse a JSON response, you typically map a Map<String, dynamic></code> into a strongly-typed Dart object.</p>
Our model looked like this:</p>
class</span> UserProfile</span> {</span></span>
  final</span> String</span> name;</span></span>
  final</span> bool</span>?</span> isPremium;</span></span>
</span>
  UserProfile</span>({</span>required</span> this</span>.name,</span> this</span>.isPremium});</span></span>
</span>
  factory</span> UserProfile</span>.</span>fromJson</span>(</span>Map</span><</span>String</span>,</span> dynamic</span>> json) {</span></span>
    return</span> UserProfile</span>(</span></span>
      name</span>:</span> json[</span>'name'</span>],</span></span>
      isPremium</span>:</span> json[</span>'isPremium'</span>],</span></span>
    );</span></span>
  }</span></span>
}</span></span></code></pre>What I Tried</h3>
I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>
What Failed</h3>
Ignoring the type cast didn’t work. The exception specifically complained about an int</code>.</p>
What Worked & Technical Explanation</h3>
I intercepted the raw HTTP response body before it hit the Dart parser.</p>
{</span></span>
  "name"</span>:</span> "Syed"</span>,</span></span>
  "isPremium"</span>:</span> 1</span></span>
}</span></span></code></pre>
The backend developer had migrated the database, and the new database driver was serializing SQL TINYINT(1)</code> boolean columns into 1</code> and 0</code> integers in the JSON payload, rather than true</code> and false</code>.</p>
Because json['isPremium']</code> contained an integer 1</code>, Dart crashed when it implicitly tried to cast it to bool?</code>.</p>
To fix this, I implemented defensive serialization</strong>. Instead of trusting the API contract blindly, the Dart parser needs to handle potential type coercion gracefully:</p>
factory</span> UserProfile</span>.</span>fromJson</span>(</span>Map</span><</span>String</span>,</span> dynamic</span>> json) {</span></span>
  </span></span>
  // Defensive parsing function</span></span>
  bool</span>?</span> parseBool</span>(</span>dynamic</span> value) {</span></span>
    if</span> (value </span>==</span> null</span>) </span>return</span> null</span>;</span></span>
    if</span> (value </span>is</span> bool</span>) </span>return</span> value;</span></span>
    if</span> (value </span>is</span> int</span>) </span>return</span> value </span>==</span> 1</span>;</span></span>
    if</span> (value </span>is</span> String</span>) </span>return</span> value.</span>toLowerCase</span>() </span>==</span> 'true'</span>;</span></span>
    return</span> null</span>;</span></span>
  }</span></span>
</span>
  return</span> UserProfile</span>(</span></span>
    name</span>:</span> json[</span>'name'</span>] </span>??</span> 'Unknown'</span>,</span></span>
    isPremium</span>:</span> parseBool</span>(json[</span>'isPremium'</span>]),</span></span>
  );</span></span>
}</span></span></code></pre>Lessons Learned</h3>

API Contracts Drift:</strong> Backend implementations change, and serialization layers can inadvertently alter the types of JSON payloads (especially converting booleans to integers or numbers to strings).</li>
Dart is Unforgiving:</strong> Unlike JavaScript, Dart will not automatically coerce 1</code> into true</code>. You must handle the conversion explicitly.</li>
</ol>
What I Would Do Differently</h3>
I will use code-generation tools like json_serializable</code> or freezed</code> with custom JsonConverter</code> classes for primitive types. This abstracts away the boilerplate of defensive parsing and ensures the entire app handles API type mismatches consistently.</p>

Syed Zubyl N | Software Developer - Dart

When API Response Types Don't Match Your Flutter Model

What I Tried</h3>
I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that `isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>`

Syed Zubyl N | Software Developer - Dart

When API Response Types Don't Match Your Flutter Model

What I Tried</h3> I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>

What I Tried</h3>
I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that `isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>`