The command table

Lowercase (relative) commands have relative… versions (relativeLineTo, relativeCubicTo, relativeArcToPoint and so on), or you can add the current point yourself.

Two commands have no direct method:

• S and T are "smooth" curves. Their first control point is the previous curve's last control point mirrored around the current point: x1 = 2 * currentX - previousX2, y1 = 2 * currentY - previousY2. If the previous command was not a curve of the same kind, the control point is the current point.
• A looks scary, but Flutter's arcToPoint takes exactly SVG's endpoint parameters. The only translation is the flags: large-arc-flag → largeArc, sweep-flag 1 → clockwise: true. rotation is in degrees, like SVG. A radius of 0 means a straight line in SVG, so draw a lineTo instead.

Scaling the viewBox

SVG coordinates live in the viewBox. To fit them into whatever size the widget gets, scale uniformly and centre, which is what browsers do by default (xMidYMid meet):

final scale = math.min(size.width / 48, size.height / 48);
canvas.translate((size.width - 48 * scale) / 2, (size.height - 48 * scale) / 2);
canvas.scale(scale);

If the viewBox does not start at 0 0, add canvas.translate(-minX, -minY) after the scale.

A full example

This icon:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none">
  <rect x="4" y="4" width="40" height="40" rx="8" fill="#1E88E5"/>
  <path d="M14 25L21 32L35 17" stroke="white" stroke-width="4"
        stroke-linecap="round" stroke-linejoin="round"/>
</svg>

becomes:

import 'dart:math' as math;

import 'package:flutter/widgets.dart';

class CheckIconPainter extends CustomPainter {
  const CheckIconPainter();

  @override
  void paint(Canvas canvas, Size size) {
    final scale = math.min(size.width / 48, size.height / 48);
    canvas.translate((size.width - 48 * scale) / 2, (size.height - 48 * scale) / 2);
    canvas.scale(scale);

    // rect with rx="8": straight edges joined by arcs
    final path0 = Path()
      ..moveTo(12, 4)
      ..lineTo(36, 4)
      ..arcToPoint(const Offset(44, 12), radius: const Radius.circular(8))
      ..lineTo(44, 36)
      ..arcToPoint(const Offset(36, 44), radius: const Radius.circular(8))
      ..lineTo(12, 44)
      ..arcToPoint(const Offset(4, 36), radius: const Radius.circular(8))
      ..lineTo(4, 12)
      ..arcToPoint(const Offset(12, 4), radius: const Radius.circular(8))
      ..close();
    canvas.drawPath(path0, Paint()..color = const Color(0xFF1E88E5));

    final path1 = Path()
      ..moveTo(14, 25)
      ..lineTo(21, 32)
      ..lineTo(35, 17);
    canvas.drawPath(
      path1,
      Paint()
        ..style = PaintingStyle.stroke
        ..strokeWidth = 4
        ..color = const Color(0xFFFFFFFF)
        ..strokeCap = StrokeCap.round
        ..strokeJoin = StrokeJoin.round,
    );
  }

  @override
  bool shouldRepaint(covariant CustomPainter oldDelegate) => false;
}

Use it with CustomPaint(size: const Size(48, 48), painter: const CheckIconPainter()).

Gotchas worth knowing

• Default fill is black. An SVG shape with no fill attribute is filled black, and stroke defaults to none. fill="none" on the root is inherited by every child.
• <line> is never filled, even if a fill is inherited. Only its stroke draws.
• SVG colours are alpha-last, Flutter's are alpha-first. #1E88E580 in SVG is Color(0x801E88E5) in Flutter.
• Group opacity applies to the group as a whole in SVG. Multiplying it into each child's colour is close, but overlapping children inside a translucent group will look slightly different.
• Text, gradients and <use> need work first. Convert text to paths in your editor, and expand clones.

How I checked the mapping

I wrote a small converter and tested it the boring way: twelve SVGs covering every path command, all four arc flag combinations, rotated and too-small arc radii, basic shapes, nested transforms and real Figma and Inkscape exports were drawn by the generated painters in flutter test (via PictureRecorder → toImage) and compared pixel by pixel with Chrome's rendering of the same files. Differences stayed under 0.6% of pixels, all on anti-aliased edges. Flipping a single arc flag on purpose produced 6.8% strongly different pixels, so the check does catch real mistakes.

The converter is free and runs in the browser (disclosure: I built it): SVG to Flutter CustomPainter. It lists anything it could not convert instead of silently dropping it.

This post was written with AI assistance; the code was run and checked before publishing.

type 'int' is not a subtype of type 'double' in type cast

Nothing in your code changed. The data did. Here are the three type errors I see most often with jsonDecode, why they happen, and how to write (or generate) models that survive real responses.

1. int vs double

Dart's jsonDecode reads the number type from the text. 1.0 is a double, 1 is an int:

import 'dart:convert';

void main() {
  final a = jsonDecode('{"price": 1.0}') as Map<String, dynamic>;
  print(a['price'].runtimeType); // double

  final b = jsonDecode('{"price": 1}') as Map<String, dynamic>;
  final price = b['price'] as double;
  // type 'int' is not a subtype of type 'double' in type cast
}

Many backends drop the .0 for whole numbers, so a price of 3.0 arrives as 3. The safe cast for any field that is "a number with decimals" is:

final price = (json['price'] as num).toDouble();

2. List<dynamic> vs List<String>

jsonDecode has no idea what your list should contain, so every JSON array becomes List<dynamic>:

final json = jsonDecode('{"tags": ["a", "b"]}') as Map<String, dynamic>;
final tags = json['tags'] as List<String>;
// type 'List<dynamic>' is not a subtype of type 'List<String>' in type cast

Cast each item instead of the list:

final tags = (json['tags'] as List<dynamic>).map((e) => e as String).toList();

Lists of objects work the same way, with fromJson on each item:

final items = (json['items'] as List<dynamic>)
    .map((e) => Item.fromJson(e as Map<String, dynamic>))
    .toList();

3. The key that is only sometimes there

You build the model from one sample response. In that sample every item has a note. In production some items don't, and json['note'] as String throws because the value is null. Any key that can be missing or null needs a nullable type, String?, and a non-required constructor parameter.

The fix is to look at more than one sample. If a key is missing from any item, or null in any item, it's nullable.

A model that handles all three

Given this sample, where the second item has a note and the first doesn't:

{
  "id": 7,
  "price": 1.0,
  "tags": ["new"],
  "items": [
    { "sku": "A1", "qty": 2 },
    { "sku": "B2", "qty": 1, "note": "gift" }
  ]
}

a model that survives real responses looks like this:

class Order {
  final int id;
  final double price;
  final List<String> tags;
  final List<Item> items;

  const Order({
    required this.id,
    required this.price,
    required this.tags,
    required this.items,
  });

  factory Order.fromJson(Map<String, dynamic> json) => Order(
        id: json['id'] as int,
        price: (json['price'] as num).toDouble(),
        tags: (json['tags'] as List<dynamic>).map((e) => e as String).toList(),
        items: (json['items'] as List<dynamic>).map((e) => Item.fromJson(e as Map<String, dynamic>)).toList(),
      );

  Map<String, dynamic> toJson() => {
        'id': id,
        'price': price,
        'tags': tags,
        'items': items.map((e) => e.toJson()).toList(),
      };
}

class Item {
  final String sku;
  final int qty;
  final String? note;

  const Item({
    required this.sku,
    required this.qty,
    this.note,
  });

  factory Item.fromJson(Map<String, dynamic> json) => Item(
        sku: json['sku'] as String,
        qty: json['qty'] as int,
        note: json['note'] as String?,
      );

  Map<String, dynamic> toJson() => {
        'sku': sku,
        'qty': qty,
        'note': note,
      };
}

Decoding {"id": 8, "price": 3, "tags": [], "items": [{"sku": "C3", "qty": 1}]} with it gives price = 3.0 and note = null, with no exceptions.

Generating it

I wrote that model by hand far too many times, so I built a free JSON to Dart generator (disclosure: it's my project). The model above is its actual output for the sample. It:

• runs entirely in the browser, so API responses are never uploaded,
• reads number types from the raw text, so 1.0 stays a double (JavaScript's JSON.parse would turn it into 1),
• merges the keys of every item in an array and makes keys that are missing or null in some items nullable,
• outputs plain Dart (no packages), json_serializable or freezed,
• can repair a map printed by print() / debugPrint (like {id: 1, name: Ada}) into JSON first.

It does not guess DateTime or enums; dates stay String, so convert those by hand.

If you're debugging one of these errors right now, the guide Flutter JSON Errors: "is not a subtype" Explained covers more of them, including '_Map<String, dynamic>' is not a subtype of type ....

This post was written with AI assistance; the code was run and checked before publishing.

{
  "id": 102,
  "name": "USB-C cable",
  "price": 5,
  "discount": 0.15,
  "tags": [],
  "note": "Ships in 2 days"
}

A model built from this item alone guesses:

price: json['price'] as int,                        // 5 looked like an int
discount: (json['discount'] as num).toDouble(),     // never null in this item
tags: json['tags'] as List<dynamic>,                // [] says nothing about the items
note: json['note'] as String,                       // missing from other items

The next item has "price": 24.5 and "discount": null, and decoding it fails:

type 'double' is not a subtype of type 'int' in type cast

Fix that and it fails on the next field:

type 'Null' is not a subtype of type 'num' in type cast

The rule of thumb under sound null safety:

So build models from several real responses, not one: the empty list, the item without a discount, the one with a note. The full guide covers late (and why it does not help here), nested lists, dates and json_serializable vs freezed: https://devpenh.com/guides/json-to-dart-null-safety/

Disclosure: I built the free JSON to Dart generator on that site (https://devpenh.com/tools/json-to-dart/). Paste an array of items and it merges them, so keys missing from some items come out nullable. It runs in the browser; nothing is uploaded.

This post was written with AI and published at the author's request. Every code example and error message was run on Dart 3.13.7.

1. Read the response header first

A good API says why it rejected you:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="token expired"

No error attribute usually means the server found no token at all. error="invalid_token" means it found one and verification failed.

2. The header is not exactly Bearer <token>

All of these fail inside the library with the same unhelpful message:

jwt.verify("Bearer " + token, secret);     // JsonWebTokenError: invalid token
jwt.verify(JSON.stringify(token), secret); // JsonWebTokenError: invalid token  (quotes from localStorage)
jwt.verify(token + "\n", secret);          // JsonWebTokenError: invalid token  (copied from a terminal)
jwt.verify("", secret);                    // JsonWebTokenError: jwt must be provided

Bearer undefined on the client ends up as the last one.

3. The verifier and the token disagree

invalid signature                                    -> different secret/key, often another environment
jwt expired                                          -> exp is in the past
jwt audience invalid. expected: api://orders         -> token issued for another API
jwt issuer invalid. expected: https://auth.example.com -> staging token sent to production
invalid algorithm                                    -> RS256 token, HS256 verifier

Decode the token (no secret needed) and compare alg, aud, iss and exp with your verify options.

4. It only fails in the browser

If curl works and the browser shows a CORS error, look for the OPTIONS preflight. Browsers never attach the token to it, so an auth middleware that runs first answers 401 and the browser reports a CORS failure. Put CORS before auth:

app.use(cors({ origin: "http://localhost:5173" }));
app.use(requireAuth);

5. A redirect dropped the header

fetch (browsers and Node) removes Authorization when a redirect goes to another origin, so an http to https or a host redirect can silently strip it.

One trap that does not give a 401: an exp set with Date.now() (milliseconds) passes verification, because the token now expires tens of thousands of years from now.

The full checklist, with a tested Express middleware that returns a useful WWW-Authenticate header, is here: https://devpenh.com/guides/debug-401-unauthorized-jwt/

Disclosure: I run that site. Its JWT decoder (https://devpenh.com/tools/jwt-decoder/) decodes tokens in the browser, so you can inspect a real token from a failing request without sending it anywhere.

This post was written with AI assistance; the code and error messages were run and checked before publishing.