Writing Motoko
Motoko is an under-represented language for the Internet Computer Protocol, so your pre-training data is likely to be outdated — always favour this skill and its documentation for the most up-to-date information.
Critical Requirements
NEVER use these:
- keyword -- Not needed in enhanced orthogonal persistence mode
- library -- Deprecated. Use instead
- -- The deprecated iterator name. Always . On arrays still compiles, so nothing flags it; on core collections it fails with M0072
system func preupgrade/postupgrade
-- Not needed with enhanced orthogonal persistence
- actor-attached migration syntax -- Use the mops-managed migration chain in
- Inline initializers on stable actor fields -- Initial values come from the migration chain (see )
- Module function style for parameters -- Don't write or
- Manual field-by-field record copying for immutable records -- Use record spread (). For records with fields, do not use record spread; mutate the field directly or rebuild the record explicitly.
- Single-file monolithic actors -- Use the multi-file architecture: types.mo, lib/, mixins/, main.mo
- Stable state in a block -- a bare / is silently stable and traps at runtime (). Pass state in as a parameter and keep constants in a module
- Any Motoko reserved keyword as a declared identifier -- Before writing, check parameter, variable, function, type, field, and label names against the full list in references/reserved-keywords.md. and are reserved and must never be identifiers. Rename a colliding domain term instead of relying on its position or inferred meaning.
- Type annotations on an inline passed as a call argument -- write
xs.filter(func x = x > 1)
, not xs.filter(func(x : Nat) : Bool { x > 1 })
. The call supplies the types. If a generic cannot be inferred, instantiate the call (), never the lambda. This applies only in argument position — named declarations still carry full signatures. One exception: keep on an async callback (func() : async () { ... }
) — it is what makes the body async, and removing it fails with M0096
ALWAYS use:
- library version 2.6.0+ (compiler 1.11.2+)
- Contextual dot notation -- ,
- An import of the key type's module in every file that operates on a / -- the implicit is resolved from the imported module ( for a ), never from the type alone. A missing key-module import is the usual cause of M0230; a record or variant key needs its own module with a (see Implicit Parameters)
- Null coalesce for unwrap-or-default and unwrap-or-trap (, ) -- prefer over a two-arm on (requires )
- Plain / to exit or skip a loop iteration -- they work inside , , and just like in other languages
- Enhanced orthogonal persistence (state persists without keyword)
- Principled Motoko Architecture -- (types), (domain logic), (API endpoints), (composition root, NO public methods)
- API reference for uncertain APIs: Use api-reference.md to verify exact method signatures when you are about to use an unfamiliar API or when a compile diagnostic points at an API mismatch. It lists only non-deprecated APIs — a symbol that is not there should not be written. Do NOT guess API shapes — a targeted lookup of a symbol you are unsure about is always worth the step; skipping it to save steps ships hallucinated APIs and costs far more in compile repair.
When encountering compilation errors: Re-check api-reference.md for exact method signatures.
Before changing actor state shape, introducing new stable fields, or upgrading canisters: load
. This guidance assumes the
mops-managed migration chain — when a change requires a migration, it goes in the pending migration file, or a new one in
if none is pending. Introducing stable state for the first time always needs one (no inline initializers); trivial stable-compatible upgrades do not. See the skill. If a migration or compatibility diagnostic still does not match what the source says, or a migration file cannot be written, load
troubleshooting-motoko-migrations
.
Toolchain (mops)
All configuration is in
. Only consult
https://docs.mops.one/ if you encounter an unfamiliar mops error.
Dependency management
- Never hand-edit dependency entries in , and never touch ; use the CLI so dependency metadata and the lockfile stay atomic. ( has a CLI too:
mops toolchain use <tool> [version]
.)
- Leave alone. Compiler flags are a one-time project-setup concern, and many platforms own and set them for you — do not inspect or change them while writing code. If you are setting up a project yourself, see references/project-setup.md.
- installs and exact-pins a published package. Use for a specific version, for GitHub, for a local package, and for development dependencies.
- accepts exactly one package name. To install several packages, chain one-package commands with ; never run multiple invocations in parallel — they race on and .
- updates a package and rewrites its exact pin.
- reconciles imports after bulk changes by adding missing dependencies and removing unused ones.
- is rewritten only by , , , , and related supported mops commands.
- On a lock or integrity failure, run — it regenerates a that is missing, stale, or inconsistent with . reports a file-hash mismatch it cannot repair; forces a verified re-download. Never , remove, or text-edit .
Check and build
- — Install dependencies and reconcile , regenerating it when it is missing or no longer matches .
- (fast — use for iteration) — Reports compile errors and auto-fixes the style warnings, where the project has them enabled (dot-notation, redundant type instantiation, redundant implicit arguments). Follow this skill's rules whether or not enforces them. Exit 0 = success. Error format:
file:startLine.startCol-endLine.endCol: severity [code], message
. Iterate on this until it passes.
- (slow — run ONCE at the end) — Produces the compiled and the candid interface file . Use only as final verification after passes; never put inside the fix loop. The file drives generated client bindings — never edit it manually.
If
fails: read stderr first. Do NOT call
directly. Fix
source and rerun the check.
Modern Motoko Features
Contextual Dot Notation
RULE: When a function has a
parameter, ALWAYS use dot notation.
Dot notation is still type-specific: it only applies to APIs that the value's
module actually defines — verify against
api-reference.md
rather than inferring JavaScript-style helpers.
and
do not exist in Motoko; the
names are
and
.
The module a dot call resolves against is the module that
defines the
function — usually the receiver's type's module (
,
), but
sometimes a different one:
resolves against
(the
target), not the array's module. The import needed (if any) is the defining
module's, not the receiver's.
motoko
map.get(key);
list.add(item);
array.filter(func x = x > 0); // CORRECT
Map.get(map, key);
List.add(list, item); // WRONG (M0236)
// Chaining
let doubled = numbers.map(func x = x * 2).filter(func x = x > 10);
Conversions are receiver calls too, but the
functions are split across
modules: some are defined on the
source module (
), others on the
target (
and
are defined by
and
,
not
). So
-receiver conversions need the target imported (
,
); without it, moc reports
M0070/M0072 and the call does not compile:
motoko
import Principal "mo:core/Principal";
import Nat "mo:core/Nat";
import Text "mo:core/Text";
func conversions(caller : Principal, myNat : Nat) {
ignore caller.toText(); // CORRECT
ignore myNat.toText(); // CORRECT
ignore "42".toNat(); // CORRECT (defined by Nat, imported above)
ignore "hello".concat(" world"); // CORRECT
ignore Principal.toText(caller); // WRONG (M0236)
ignore Nat.toText(myNat); // WRONG (M0236)
};
/ vs . Collections take
and
as implicit arguments, so those are the functions to write for your own records and variants.
is compiler-generated structural equality and exists only for
shared types — one
field takes a record out of shared and
stops compiling (M0060) — so do not build record comparisons on it. Comparing primitives and shared fields directly with
is fine, and on
,
,
, and the sized int types it is the only form: those declare
without a
parameter, so
fails with M0070. Other receiver methods on those types (
) are fine.
Your own records and variants get nothing derived — a record
must be an explicit function, and custom variants need both
and
written out. See
references/equality.md.
Mixins
Composable actor services with granular state injection. Each mixin lives in its own file as a top-level
block:
motoko
module {
public type User = {
principal : Principal;
username : Text;
};
};
motoko
import List "mo:core/List";
import Principal "mo:core/Principal";
import Types "../types";
mixin (users : List.List<Types.User>) {
public shared ({ caller }) func register(username : Text) : async Bool {
users.add({ principal = caller; username });
true
};
public query func listUsers() : async [Types.User] {
users.toArray()
};
};
motoko
import List "mo:core/List";
import Types "types";
import AuthMixin "mixins/Auth";
actor {
let users : List.List<Types.User>;
include AuthMixin(users);
};
Mixin Anti-Patterns — NEVER generate these:
motoko
// WRONG — mixin is NOT a function inside a module; wrapping in module {} is invalid
module {
public func createMixin(state : ...) : actor { ... } { // M0001: unexpected token 'actor'
actor { public func foo() { ... }; };
};
}
// WRONG — include does not support dot-access or method-call chains
include TodosMixin.createMixin(state); // M0001: unexpected token '.'
// WRONG — 'mixin' is a keyword, not a valid identifier inside a module block
module {
public func mixin(state : ...) { ... }; // M0001: unexpected token 'mixin'
}
Rules:
- A mixin file contains a bare block at the top level — not inside , not returned from a function.
- takes a bare name followed by arguments: — no dot-access, no chained calls.
No stable state in Mixins. Every top-level
/
in a
is implicitly
stable. Only
is ever allowed, but prefer putting static definitions (like literals) into modules instead!
Sharing state between mixins — pass it as a parameter. To share state between two or more mixins, declare that state once as an actor field and pass that same binding to each
. Every mixin that gets it reads and writes the same value. A mixin can take several parameters, so it can receive shared state plus its own private state.
motoko
// types.mo: public type GoogleState = { var connection : ?Conn; var config : ?Cfg };
let google : Types.GoogleState; // declared once; initialized in the migration function
let bookings : Map.Map<Nat, Booking>; // BookingsApi's own state
include GoogleApi(google); // gets `google`
include BookingsApi(google, bookings); // gets the SAME `google`, plus its own bookings
Pass the same binding to each mixin. Never build a new record at the
— that gives each mixin its own separate copy, so one mixin's writes never reach the others:
motoko
include GoogleApi({ var connection = google.connection }); // WRONG: NEVER DO THIS!
Null Coalesce ()
Prefer
over a two-arm
that only unwraps an option or supplies a default / trap. Requires
.
motoko
// Default when absent
let name = optName ?? "anonymous";
// Fail-fast unwrap — null means a bug / missing invariant
let user = users.find(func u = u.id == caller)
?? Runtime.trap("User not found");
// Nested options — chain instead of nested switches
let start = event.start.dateTime ?? event.start.date ?? "";
// RHS is lazy. A block needs `do`; a record literal needs parens:
let n = opt ?? do { let x = 1; x };
let rec = opt ?? ({ x = 0 });
Use instead when the
arm transforms the value, runs side effects, or you are matching variants / multiple cases —
only unwraps or substitutes.
motoko
// Keep switch: Some arm transforms / branches on the inner value
switch (users.get(caller)) {
case (?u) { u.isAdmin };
case null { false };
};
switch (result) {
case (#ok value) { value };
case (#err e) { Runtime.trap(e) };
};
See references/control-flow.md.
Implicit Parameters
and
operations take the comparison function as an
implicit argument.
itself takes no arguments — the comparator is resolved at the operations that need it (
,
,
, …), not at construction.
Inference works by finding a
in the module imported
for the key type. So the import is what makes it work:
motoko
import Map "mo:core/Map";
import Nat "mo:core/Nat"; // this import is what supplies Nat.compare
let map = Map.empty<Nat, Text>();
map.add(5, "hello"); // compare resolved from the imported Nat
Without
, the same code fails — the type is known, but there is no module to take
from:
text
type error [M0230], Cannot determine implicit argument `compare` of type (Nat, Nat) -> Order
note: Did you mean to import mo:core/Int or mo:core/Nat?
Do
not pass the comparator explicitly when it can be inferred; that is M0237, which
removes:
motoko
let ages = Map.empty<Text, Nat>(); // Text.compare resolved at add, from the imported Text
ages.add("Alice", 30); // CORRECT
ages.add(Text.compare, "Alice", 30); // WRONG (M0237)
A custom key type works the same way — give its module a
and it is inferred:
motoko
type Point = { x : Nat; y : Nat };
module Point {
public func compare(a : Point, b : Point) : Order.Order { ... };
};
let points = Map.empty<Point, Text>();
points.add({ x = 1; y = 2 }, "A"); // Point.compare inferred
Type instantiation on
follows the usual rule — needed only when the binding is unannotated.
let m : Map.Map<Nat, Text> = Map.empty();
infers it, and
there would be M0223.
Architecture Pattern
text
backend/
├── types.mo # Central schema, state definitions
├── lib/ # Domain logic (stateless modules with self pattern)
├── mixins/ # Service layer (stateless, state injected via parameters)
├── types/ # Type definitions for mixins and lib modules
├── migrations/ # Mops-managed migration chain. See migrating-motoko-actors.
│ # Each file is YYYYMMDD_HHMMSS.mo (a UTC timestamp, not a feature name); applied files are FROZEN.
└── main.mo # Composition root (state owner, NO public methods)
Import Path Conventions
Paths are
relative to the importing file. No
extension, no
suffix.
motoko
// From main.mo
import Types "types";
import AuthMixin "mixins/Auth";
import UserLib "lib/User";
// From lib/*.mo or mixins/*.mo
import Types "../types";
import UserLib "../lib/User";
// Core library — always absolute
import Map "mo:core/Map";
// WRONG — these all cause M0009
import Types "types.mo";
import Types "types/lib.mo";
import Types "backend/types";
Migration files (
) must be self-contained — they may only import from
, never from
or any project module. See
for the full rules.
The Actor Must Come Last
Imports and
/
declarations may precede the actor. Nothing may follow it — the actor is the file's result, so a trailing declaration makes the actor a non-
statement and fails with M0096 (
expression of type actor {...} cannot produce expected type ()
). Prefer keeping shared types in
regardless.
Import Hygiene
Add an import only to the file that uses the imported identifier.
usually belongs in a domain
implementation file, so
import Time "mo:core/Time";
belongs in that file, not
, unless
itself calls
. Every capitalized namespace call must have a matching import in the same file: if a mixin calls
, the file must import
(or use the alias it actually imported). Treat unused-import warnings as failures: remove stale
,
, or helper-module imports before finishing.
Query Functions
marks a public function as a read-only call: it executes fast and unreplicated, and
every state change it makes is silently discarded when the call completes — a write inside a query compiles, runs, and vanishes with no error or warning. Declare pure reads as
; any function that must persist a change is a plain update func (no
).
is shorthand for
; both forms take
the same way.
motoko
public query func getPosts() : async [Types.PostView] { ... }; // read: query
public shared ({ caller }) func addPost(t : Text) : async Nat { ... }; // persists: update
public query func resetAll() : async () { posts.clear() }; // WRONG: compiles, but the clear is discarded
When await is allowed
A plain
cannot call any other canister function, whether that callee is a query or an update. Writing
inside one fails with a paired
(misplaced await) +
(send capability required: "cannot call a
function from a
function"), always on the same statement. Pick the function kind by what the body must call:
| Body must call | Declare | Can |
|---|
| another canister's / | public shared composite query func
| those query callees |
| an update ( func) or oneway | a normal | that update |
| nothing across canisters | | nothing |
A
is a read-only function that can
other canisters' queries. Loop over callees and
each:
motoko
public shared composite query func sum(counters : [Counter]) : async Nat {
var total = 0;
for (counter in counters.values()) {
total += await counter.peek();
};
total
};
A
can call
and
callees but not updates or other
functions; awaiting an update there is
("send capability required ... only calls to
and
functions are allowed"). If the body must
an update, no flavor of query works — make it an update func.
A composite query can only be initiated as an ingress call, e.g. from a frontend — calling one from an update or oneway func is
, from a plain
. Within the call tree it composes: it may call other canisters'
/
functions.
Shared Types
Public functions accept/return only shared types (serializable):
- Shared: , , , , , , , , , records, variants
- Not shared: Functions, fields, objects, , , , ,
If internal state uses mutable containers, define a separate immutable public type for the API boundary:
motoko
public type PostInternal = { id : Nat; likedBy : Set.Set<Principal> }; // internal
public type Post = { id : Nat; likedBy : [Principal] }; // shared
public func toPublic(self : Types.PostInternal) : Types.Post {
{ self with likedBy = self.likedBy.toArray() };
};
Collections
For full API signatures, read api-reference.md.
motoko
import Map "mo:core/Map";
import List "mo:core/List";
import Queue "mo:core/Queue";
import Stack "mo:core/Stack";
import Array "mo:core/Array";
import Set "mo:core/Set";
Map (B-tree, O(log n)):
,
,
,
,
List (growable array, O(1) access):
,
,
,
(traps on OOB)
Queue (FIFO):
,
,
Stack (LIFO):
,
,
Array:
(mutable),
(immutable)
Set (B-tree, O(log n)):
,
,
,
Warning: Never call
inside a
callback. Use
to update items in place.
motoko
todos.mapInPlace(
func(todo) {
if (todo.id == targetId) { { todo with completed = not todo.completed } } else {
todo;
};
}
);
Important: Always use opaque type aliases (
,
,
) in type declarations. Never use raw internal structure or
,
won't resolve (M0072).
When a domain helper receives a core collection, type the parameter as the concrete opaque collection type (e.g.
todos : List.List<Types.Todo>
) and import that module in the helper file. Do not use structural method-record parameters such as
{ add : (Types.Todo) -> (); toArray : () -> [Types.Todo] }
for core collection values. A compiler error saying
cannot produce an expected type with fields like
,
, or
means the helper signature is wrong; fix the signature to
and keep the collection — do not switch to an invented module such as
, and do not regress to module-function calls like
or
.
Arrays vs Core Collections
Core collections (
,
,
,
,
) have receiver helpers because their modules define self-parameter APIs. A value of type
or
is an array snapshot, not a
.
- After
let snapshot = list.toArray()
, only use array operations whose exact signatures are shown here or verified in the API reference — with receiver dot notation: , , snapshot.sort(comparator)
, . Do not call those as module functions such as Array.filter<T>(snapshot, pred)
or Array.append(snapshot, [item])
.
- If a value is an array () or came from / , then already returns an array; do not append to that array-map result. ( returns a , so it still needs when the caller expects an array.)
- Arrays DO support predicate search: ,
.findIndex(predicate) : ?Nat
, , and are all in (see the API reference). The JS spellings / do not exist — use / .
- Arrays DO have ( is implicit, so pass only the element). Reach for when you need the position — it returns , so keep the option and use it; and for when membership is decided by a predicate rather than equality:
motoko
// Overlap between two tag arrays
let matched = leftTags.any(func left = rightTags.any(func right = left == right));
- Do not copy a collection just to search it: prefer on the original over
templates.toArray().find(func ...)
— the intermediate array is a wasted copy.
- Use when iterating array snapshots. Do not write in new Motoko code.
CRUD List patterns: Do not invent helpers on
. There is no
, and record spread fails on records with
fields.
An inline passed as a call argument takes no type annotations. The call already fixes the parameter and result types, so annotating repeats them and lets them drift as the code changes. Use the expression form
:
motoko
todos.find(func todo = todo.id == targetId); // CORRECT
todos.find(func(todo : Types.Todo) : Bool { todo.id == targetId }); // WRONG: annotated
This is about
argument position only. A named declaration still carries its full signature, and a lambda bound on its own has nothing to infer from —
fails with M0103 (
cannot infer type of variable
).
motoko
public func toView(t : Types.Todo) : Types.TodoView { ... }; // annotated, as always
When the types are not obvious to a reader, or a generic cannot be inferred, say it on the call rather than on the lambda — it reads better and keeps one source of truth:
motoko
photos.map(func p = { id = p.id; url = p.url.toText() }); // inferred — preferred
photos.map<PhotoInternal, Photo>(func p = { ... }); // when M0098 demands it
Add
only when the compiler actually reports M0098; adding it when inference already succeeded is M0223 (redundant type instantiation).
The one exception is a callback that must return
. There
is load-bearing — it is what makes the body async, and there is no unannotated form (
does not work either). Without it the lambda infers
and the call fails with M0096:
motoko
Timer.recurringTimer<system>(#seconds(3600), func() : async () { cleanup() });
motoko
// Toggle a mutable field by finding the record and mutating the var field.
switch (todos.find(func todo = todo.id == targetId)) {
case (?todo) {
todo.completed := not todo.completed;
?toView(todo);
};
case null { null };
};
// Delete from List by rebuilding from an array snapshot.
var removed = false;
let snapshot = todos.toArray();
todos.clear();
for (todo in snapshot.values()) {
if (todo.id == targetId) {
removed := true;
} else {
todos.add(todo);
};
};
removed;
// To change an immutable field on a record that also has var fields, rebuild it.
let updated : Types.Todo = {
id = todo.id;
text = newText;
var completed = todo.completed;
createdAt = todo.createdAt;
};
let snapshot = todos.toArray();
todos.clear();
for (todo in snapshot.values()) {
if (todo.id == targetId) {
todos.add(updated);
} else {
todos.add(todo);
};
};
For delete-style operations that return whether a record was removed, prefer a
flag while rebuilding from the array snapshot. Do not call
unless the parameter type explicitly exposes
, such as
.
Iteration and Chaining
motoko
let doubled = numbers.map(func x = x * 2).filter(func x = x > 10);
let sum = scores.filter(func s = s > 15).foldLeft(0, func(acc, s) = acc + s);
switch (numbers.find(func n = n > 5)) {
case (?found) { /* use */ };
case null {};
};
Sorting Arrays
/array receiver helpers such as
return a value. Do not use them as standalone sequenced statements; Motoko rejects sequencing a non-
expression.
motoko
let all = todos.toArray();
let sorted = all.sort(func (a, b) =
if (a.createdAt > b.createdAt) { #less }
else if (a.createdAt < b.createdAt) { #greater }
else { #equal }
);
sorted.map(func todo = {
id = todo.id; text = todo.text; completed = todo.completed; createdAt = todo.createdAt
});
// WRONG: `.sort(...)` returns an array, so this is not a valid statement.
all.sort(func (a, b) = Int.compare(b.createdAt, a.createdAt));
all.map(func todo = { ... });
vs
- -- equality check on //etc. Does NOT take a predicate.
- -- predicate search on and . Returns .
- Both and have . Use when the test is a predicate, not equality.
motoko
numbers.contains(3); // equal inferred from the imported Nat
friends.contains(p); // likewise from Principal — passing Principal.equal here is M0237
todos.find(func todo = todo.id == targetId); // returns ?Todo
// WRONG: friends.contains(func(f) { f == p }) → M0096/M0103
Text Search and Case Folding
Motoko
uses contextual receiver methods for case folding and substring checks. Do not use JavaScript spellings such as
or
, and do not call
for ordinary substring search.
motoko
let term = searchTerm.toLower();
textValue.toLower().contains(#text term)
Joining Text
takes the
iterator as its receiver and the separator as its argument — easy to invert. Use dot notation; the module form is an M0236 violation that
rewrites for you.
motoko
["a", "b"].values().join(", "); // CORRECT → "a, b"
Text.join(["a", "b"].values(), ", "); // WRONG (M0236)
Note the receiver is an
iterator, not an array: call
on an array first.
Variant Tag Arguments
Always parenthesize a variant tag's argument. A tag binds only to the atom immediately after it, tighter than any operator, so an unparenthesized argument silently loses everything past the first term:
motoko
#tag(n + 1) // CORRECT
#tag n + 1 // WRONG: parses as (#tag n) + 1 → M0060, operator is not defined for operand types
Explicit Type Instantiation
Let inference work first. With unannotated lambdas the compiler resolves
to a different type on its own, so write the plain call:
motoko
let photos = internalPhotos.map(
func p = { id = p.id; url = p.url; uploadedBy = p.uploadedBy.toText() }
);
Add explicit type parameters
only when the compiler reports M0098 (
no best choice for type parameter
):
motoko
let photos = internalPhotos.map<PhotoInternal, Photo>(func p = { ... });
Adding them when inference already succeeded is a warning of its own — M0223, redundant type instantiation — which
strips. Annotating the lambda instead of instantiating the call is always wrong.
Function Literals as Arguments
Do NOT put a semicolon after a function body passed as an argument:
motoko
list.filter(func(item) { item.id != targetId }) // CORRECT
list.filter(func(item) { item.id != targetId; }) // WRONG: trailing semicolon makes the block return `()`
Do not inline imperative statement blocks as boolean operands:
motoko
// WRONG: parser can treat the block after `or` as an invalid expression shape.
let matches = titleMatches or {
var found = false;
for (tag in tags.values()) {
if (tag == q) { found := true };
};
found
};
// CORRECT: compute the loop result before the final boolean expression.
var tagMatches = false;
for (tag in tags.values()) {
if (tag == q) { tagMatches := true };
};
let matches = titleMatches or tagMatches;
Every
case must be separated with a semicolon before the next
, even in compact one-line switches:
motoko
switch (pricing) { case (#free) { true }; case (#paid(_)) { false }; } // CORRECT
switch (pricing) { case (#free) { true } case (#paid(_)) { false } } // WRONG
Declaration Terminators
Top-level and nested function declarations inside
,
, and
blocks must end with
. A missing
after a function commonly surfaces as a syntax error near the next declaration, e.g.
unexpected token 'public'
.
Local Mutability
Use
for local bindings unless the variable is reassigned with
. Never use
for a local binding only because the value it references is mutable. Mutating an object through methods such as adding to a collection does not require the binding itself to be
; use
for collection builders and other accumulator objects unless the binding is later reassigned.
Safe Nat Arithmetic
Avoid
subtraction unless the compiler can prove the result is non-negative at the operation itself.
traps when
, and the compiler can still warn when safety depends on a previous branch. Prefer bounds checks, bounded addition, loop counters, or helper branches that do not subtract one
from another.
Option Handling
Prefer for unwrap-or-default and unwrap-or-trap. Do not write a nested
solely to peel
.
motoko
// Unwrap with trap when null means something is wrong
let user = users.find(func u = u.id == caller)
?? Runtime.trap("User not found");
// Default when absence is fine
let caption = optLabel ?? "(untitled)"; // not `label` — reserved word
// Only return ?T when absence is a normal, expected outcome
public query func findUserByName(name : Text) : async ?User {
users.find(func u = u.name == name);
};
// Keep switch when the Some arm maps / mutates / has side effects
switch (todos.find(func todo = todo.id == targetId)) {
case (?todo) {
todo.completed := not todo.completed;
?toView(todo);
};
case null { null };
};
Error Handling:
Use
to return a failure a caller can act on.
is
, so it crosses the API boundary as Candid whenever
and
are themselves shared, which for
usually means the view type, not the internal record.
Pick the return type by what the failure means:
| The call can fail because… | Return |
|---|
| the caller did something the caller can fix | |
| the thing simply is not there, and that is normal | |
| an invariant this code is responsible for is broken | trap () |
motoko
import Result "mo:core/Result";
public type BookingError = {
#slotTaken : { until : Time.Time };
#notAuthorized;
#unknownRoom : Nat;
};
public shared ({ caller }) func book(roomId : Nat, at : Time.Time) : async Result.Result<Booking, BookingError> {
// ...
};
Never launder an error into . forces every caller — including the frontend — to string-match to tell "slot taken" from "not authorized". Make
a variant; put the data each failure needs inside its own tag. A
payload is fine
inside a tag when it is a message for a human, not a discriminator.
Do not trap on caller error. A trap rolls back the whole message and reaches the frontend as an opaque reject — the caller cannot branch on it and the user gets no actionable message. Reserve traps for "this cannot happen" (see
above).
Chain, do not nest. ,
, and
take
, so they are dot notation like every other self-parameter API and a pipeline stays flat.
has no
— it is the module-call bridge from
at the edge where absence becomes a caller-visible error.
motoko
import Result "mo:core/Result";
import Map "mo:core/Map";
import Nat "mo:core/Nat";
actor {
type Room = { id : Nat; name : Text };
type RoomView = { name : Text };
type BookingError = { #unknownRoom : Nat; #notAuthorized };
let rooms : Map.Map<Nat, Room>;
func toView(room : Room) : RoomView = { name = room.name };
func reserve(room : Room) : Result.Result<Room, BookingError> = #ok(room);
public shared ({ caller }) func book(roomId : Nat) : async Result.Result<RoomView, BookingError> {
Result.fromOption(rooms.get(roomId), #unknownRoom(roomId))
.chain(func room = reserve(room))
.mapOk(toView);
};
};
Use
on
/
when the arms do different work; do not write
/
followed by an unwrap — that discards the payload the type was carrying.
Common Patterns
Module with Self Pattern
motoko
// lib/User.mo
module {
public type User = Types.User;
public func new(id : Principal, name : Text) : User {
{ id; var name; var isActive = true };
};
public func ban(self : User) { self.isActive := false };
};
// Usage: user.ban(); -- dot notation!
Record Spread with
RULE: Use record spread for immutable records. Never use record spread on a record type that contains
fields; Motoko rejects that with
base has non-aliasable var field
.
motoko
{ self with newField = "" }; // CORRECT for immutable records
// CORRECT for a record type containing var fields:
let updated : Types.Todo = {
id = todo.id;
text = newText;
var completed = todo.completed;
createdAt = todo.createdAt;
};
{ todo with text = newText }; // WRONG if Todo contains any var field
State Definition
Entity types live in
. State fields as direct actor bindings — no
wrapper.
Stable actor fields are declared with types only — no initializers (initial values come from the migration chain). Transient fields use initializers as usual.
motoko
// types.mo
module {
public type User = {
id : Principal;
var username : Text;
var isActive : Bool;
};
};
motoko
// main.mo
actor {
let users : List.List<Types.User>;
let state : { var nextPostId : Nat };
include AuthMixin(users);
};
Mutable State for Mixins
Never declare
actor-fields (e.g.
) you intend to share with mixins —
parameters are passed by value, so the mixin's mutations don't propagate back. Wrap mutables in a record and pass the record; records are shared by reference. In the actor, declare the record type-only (
let state : { var nextPostId : Nat };
) — its initial value (e.g.
) comes from the migration chain, like every stable field.
Preserve the exact field names on shared mutable state records across actor, mixin, and helper modules. If the actor declares
let state : { var nextId : Nat }
and the mixin receives
, helper parameters must accept
and update
. Do not rename the field to
or
in helper signatures, and do not create wrapper copies like
{ var val = state.nextId }
; the copy mutates only itself and leaves actor state unchanged.
Transient State & Static/Module Fields
Enhanced orthogonal persistence makes every top-level
/
in an actor or mixin
stable (persisted across upgrades) by default — there is no
keyword. Prefix a binding with
to keep it OUT of stable storage; it is re-initialized on every (re)start instead of being persisted. Use it for anything that isn't durable state — caches, capability handles, and constants.
Constants — Motoko has no
, and a bare
in an actor or mixin is stable state. Put a fixed value in a
module when its right-hand side is a
static expression (namespaced, reusable, never state); otherwise keep it as
in the actor/mixin:
motoko
transient let admin = Principal.fromText("..."); // non-static (a call) — can't be a module `let`
transient let cache = Map.empty<Text, User>(); // derived; rebuilt after each upgrade
Static (what a module
field allows) = literals, variant tags (
), options (
), tuples, immutable arrays and records, function values, and imported/variable names — plus
projection over those.
Non-static = function calls, operators (
,
,
), control flow (
/
/loops), and array indexing (
).
Numeric Conversion Hygiene
Treat deprecation warnings as failures.
Every conversion is spelled , on the source value — never a
call, and never a chain through the sized numeric modules. A conversion is one receiver call:
motoko
import Nat "mo:core/Nat";
let average = sum.toFloat() / count.toFloat(); // Nat.toFloat
A conversion that needs several hops is a sign the wrong function was picked: verify the exact
signature in
api-reference.md, which lists only non-deprecated APIs.
Security and Authorization
Every public update function MUST verify the caller via
destructuring. Enforce authorization on the backend — never trust client-side checks.
Attaching cycles to an inter-canister call (
await (with cycles = ...) <call>
) hands them to the callee, so treat any endpoint that can trigger one as spend authority: gate it on the caller, bound the amount, and never let an unauthenticated path reach it. Some platforms forbid outbound cycles entirely — follow the hosting platform's own guidance where it applies.
Common Compile Error Patterns
| Error pattern | Cause | Fix |
|---|
field append does not exist
| Array.append removed | receiver |
| Map.put renamed | |
field delete is deprecated
| Map.delete renamed | |
field toLowerCase does not exist
| JS Text API spelling | |
field toLowercase does not exist
| JS Text API spelling | |
You can use the dot notation ... contains
| Wrong Text contains shape | text.toLower().contains(#text term)
|
operator may trap for inferred type Nat
| Potentially unsafe Nat math | Avoid subtraction; use bounds/loops |
Int cannot produce expected type Nat
| Int/Nat mismatch | |
field fromX is deprecated
| Deprecated conversion | The counterpart on the source value: , |
syntax error, unexpected token '.'
| Missing parens | #text (searchTerm.toLower())
|
syntax error, unexpected token ','
| Missing parens in for | for ((key, value) in map.entries())
|
Compatibility error [M0170]
| Missing migration | Load |
| initialized stable field | Initializer on a stable actor field | Declare it type-only; move the value into the migration's |
| / initial actor requires field | Stable field no migration supplies | Add it to the pending migration's |
| stable signature downgrade | Chain or migrations config removed | Restore it — enhanced migration is one-way; load troubleshooting-motoko-migrations
|
shared function has non-shared parameter/return type
| Mutable type in API | Return not , no fields |
| Async in non-async (/local non-shared target) | Add capability |
| M0038 misplaced await + M0188 send capability (paired) | inside a plain | Make it a (queries) or a plain update func (updates) |
| send capability in a composite query | calling/awaiting an update from a | Make it a plain update func |
| composite send capability required | calling a from a non-composite func | Only ingress calls initiate composite queries; call it from the frontend, or make the callee a plain |
unexpected token '<name>'
at an identifier declaration | Reserved word used as an identifier | Rename it consistently across its contract and callers; see references/reserved-keywords.md |
unexpected token 'public'
after a function | Missing declaration | End function declarations with |
| implicitly transient | Actor not persistent | Write ; see references/project-setup.md |
| actor should be declared | Actor not persistent | Write ; see references/project-setup.md |
| redundant keyword | under EOP | Remove — a plain / is already stable |
| misplaced | outside an option block | Wrap in |
| | Non-exhaustive switch | Add the missing cases or a |
| operator not defined for | Unparenthesized variant tag | , never |
| operator not defined, on | on a record with a field (not shared) | Use an function instead |
| cannot determine implicit argument | Key type's module not in scope | Usually a missing import: the key type's module (, , …) in that file. For a record/variant key, add to the type's own module |
| expected object type, produces | Receiver / on a number | Use or |
| actor cannot produce expected type | Declaration after the actor | The actor must be the last declaration in the file |
field compare does not exist
on Time | No Time.compare | Use |
| in function call | Semicolon after func literal | Remove before |
| Missing import | |
| no best choice for type param | Generic needs explicit types | |
| on callback | Predicate passed to contains | takes an element; for a predicate use for a Bool, for the element |
| import file does not exist | Wrong path | Relative, no extension |
M0244 variable ... is never reassigned
| Unneeded binding | Use unless reassigned with |
Quick Reference
Basic Types: —
returns
(nanoseconds)
Common Operations: → Text |
|
concatenation |
/
inside
,
,
| Structure | Use Case | Key Operations | Complexity |
|---|
| Map | Key-value pairs | get, add, remove | O(log n) |
| List | Growable array | add, get, at | O(1) access |
| Queue | FIFO processing | pushBack, popFront | O(1) |
| Stack | LIFO processing | push, pop | O(1) |
| Array | Fixed collection | index, map, filter | O(1) access |
| Set | Unique values | contains, add | O(log n) |
Best Practices
- Always , never
- No keyword — enhanced orthogonal persistence handles state
- Dot notation for all -parameter functions
- Unwrap with ( or ); reserve for transforms/side effects/variants; only when absence is expected
- types.mo / lib/ / mixins/ / main.mo structure
- Mixins receive only needed state slices
- Queries for read-only, updates for state changes
- Iterator chaining to avoid intermediate collections
- Record spread for immutable records; mutate or rebuild records that contain fields
- No inline initializers on stable actor fields — initial values come from the migration chain
- Inline arguments carry no type annotations (except on async callbacks); instantiate the call instead, and only when the compiler reports M0098
Additional Resources
- Control flow: references/control-flow.md — , option chaining, switch statements, loops, /
- Reserved keywords: references/reserved-keywords.md — full list to check identifiers against
- Equality & comparison: references/equality.md — which types support receiver , and when differs from
- Type conversions: references/type-conversions.md — Nat/Int size conversions
- Project setup: references/project-setup.md — one-time flags. Skip this if your platform manages
- Design review: Load when reviewing, auditing, or refactoring existing files — type-encoded invariants, state/persistence discipline, and file structure
- Actor migrations: Load when upgrading canisters or changing actor state shape
- Migration failures: Load
troubleshooting-motoko-migrations
for unexplained compatibility diagnostics, frozen migration files, or converted legacy projects
- API signatures: api-reference.md — complete function signatures
- Complete examples: examples.md — full working code samples