Motoko

Writing actor instead of persistent actor. Since moc 0.15.0, the persistent keyword is mandatory on all actors and actor classes. Plain actor produces error M0220.

// Wrong — error M0220: this actor or actor class should be declared `persistent`
actor {
  var count : Nat = 0;
};

// Correct
persistent actor {
  var count : Nat = 0;
};

// Actor classes also require it
persistent actor class Counter(init : Nat) {
  var count : Nat = init;
};

Putting type declarations before the actor. Only import statements are allowed before persistent actor. All type definitions, let, and var declarations must go inside the actor body. Violation produces error M0141.

// Wrong — error M0141: move these declarations into the body of the main actor or actor class
import Nat "mo:core/Nat";

type UserId = Nat;
let MAX = 100;
persistent actor {};

// Correct
import Nat "mo:core/Nat";
persistent actor {
  type UserId = Nat;
  let MAX = 100;
};

Using stable keyword in persistent actors. In persistent actor, all let and var declarations are stable by default. Writing stable var is redundant and produces warning M0218. Use transient var for data that should reset on upgrade.

persistent actor {
  // Wrong — warning M0218: redundant `stable` keyword
  stable var count : Nat = 0;

  // Correct — implicitly stable
  var count : Nat = 0;

  // Correct — resets to 0 on every upgrade
  transient var requestCount : Nat = 0;
};

The old keyword flexible was renamed to transient in moc 0.13.5. Never use flexible.

Using HashMap, Buffer, TrieMap, or RBTree in persistent actors. These types from the old base library contain closures and are NOT stable. Using them in a persistent actor produces error M0131. They do not exist in mo:core — the modern standard library has stable replacements.

// Wrong — these types do not exist in mo:core and are not stable
import HashMap "mo:base/HashMap";
import Buffer "mo:base/Buffer";

// Correct — use mo:core stable collections
import Map "mo:core/Map"; // key-value map (B-tree, stable)
import Set "mo:core/Set"; // set (B-tree, stable)
import List "mo:core/List"; // growable list (stable)
import Queue "mo:core/Queue"; // FIFO queue (stable)

Reassigning let bindings. let is immutable in Motoko — there is no reassignment. Use var for mutable values.

// Wrong — cannot assign to immutable let binding
let count = 0;
count := 1;

// Correct
var count = 0;
count := 1;

// Also correct — let is fine for collections (they mutate internally)
let users = Map.empty<Nat, Text>();
Map.add(users, Nat.compare, 0, "Alice"); // mutates the map in place

Using continue or break without labels (moc < 1.2.0). Unlabeled break and continue in loops require moc >= 1.2.0. For older compilers, or when targeting an outer loop, use labeled loops.

// Works since moc 1.2.0
for (x in items.vals()) {
  if (x == 0) continue;
};

// Required for moc < 1.2.0, or to target a specific loop
label outer for (x in items.vals()) {
  label inner for (y in other.vals()) {
    if (y == 0) continue inner;
    if (x == y) break outer;
  };
};

Shared function parameter types must be shared. All parameters and return types of public actor functions must be shared types. Closures, mutable records, Error, and async* are NOT shared types. Error codes: M0031, M0032, M0033.

// Wrong — functions are not shared types
public func register(callback : () -> ()) : async () {};

// Wrong — mutable records are not shared types
public func store(data : { var count : Nat }) : async () {};

// Correct — use immutable records and avoid closures
public func store(data : { count : Nat }) : async () {};

Incomplete pattern matches. Switch expressions must cover all possible values. Missing cases produce error M0145.

type Color = { #red; #green; #blue };

// Wrong — error M0145: pattern does not cover value #blue
func name(c : Color) : Text {
  switch (c) {
    case (#red) "Red";
    case (#green) "Green";
  };
};

// Correct — cover all cases (or use a wildcard)
func name(c : Color) : Text {
  switch (c) {
    case (#red) "Red";
    case (#green) "Green";
    case (#blue) "Blue";
  };
};

Variant tag argument precedence. Variant constructors with arguments bind tightly. When passing a complex expression, use parentheses to avoid unexpected parsing.

type Action = { #transfer : Nat; #none };

// Potentially confusing — what does this parse as?
let a = #transfer 1 + 2; // parsed as (#transfer(1)) + 2 — type error

// Clear — use parentheses for complex expressions
let a = #transfer(1 + 2); // #transfer(3)

Using do ? { } blocks incorrectly. The ! operator (null break) only works inside a do ? { } block. Using it outside produces error M0064.

// Wrong — error M0064: misplaced '!' (no enclosing 'do ? { ... }' expression)
func getName(map : Map.Map<Nat, Text>, id : Nat) : ?Text {
  let name = Map.get(map, Nat.compare, id)!;
  ?name;
};

// Correct — wrap in do ? { }
func getName(map : Map.Map<Nat, Text>, id : Nat) : ?Text {
  do ? {
    let name = Map.get(map, Nat.compare, id)!;
    name;
  };
};