Docs / CLI / Fixing build errors

Fixing build errorsalpha

Read moxzi's error messages, fix the common ones, and tell a mistake in your code from a compiler bug.

moxzi prints errors in the same format as moc, with the same codes, so a search for a code finds Motoko documentation that applies to moxzi too. This page shows how to read an error and how to fix the ones you'll see most.

Reading an error#

Error: compilation failed:
/src/type.mo:2.21-2.27: type error [M0050], literal of type Text does not have expected type Nat

Part	Meaning
`/src/type.mo`	The file, as the compiler sees it. `/src/` is your project directory; `/pkg/NAME/` is a package
`2.21-2.27`	Line 2, columns 21 to 27
`type error`	The kind: `syntax error`, `type error`, or `warning`
`[M0050]`	The error code. The same code means the same thing in `moc`
the rest	What's wrong

The build stops at the first stage with errors and prints every error from that stage. Warnings are printed even when the build succeeds; see Building for -E and -A.

Common errors#

Wrong type#

type.mo

actor {
  var count : Nat = "zero";
};

Error: compilation failed:
/src/type.mo:2.21-2.27: type error [M0050], literal of type Text does not have expected type Nat

The value doesn't match the declared type. Change one or the other. M0096 is the same error for an expression that isn't a literal.

Undefined name#

unbound.mo

actor {
  public func total() : async Nat {
    count + 1
  };
};

Error: compilation failed:
/src/unbound.mo:3.5-3.10: type error [M0057], unbound variable count

count isn't declared anywhere in scope. Check the spelling, or declare it.

Missing field#

field.mo

actor {
  let user = { name = "ada"; age = 36 };

  public query func email() : async Text {
    user.email
  };
};

Error: compilation failed:
/src/field.mo:5.5-5.15: type error [M0072], field email does not exist in object with fields: age, name

The message lists the fields the object does have.

Import not found#

import.mo

import Utils "lib/Utils";

actor {};

warning: could not resolve import "lib/Utils"; not uploading it (project root .: packages none (no mops.toml); the nearest mops.toml or dfx.json above the entry file picks the root)
Error: compilation failed:
/src/import.mo:1.14-1.25: type error [M0020], unresolved import lib/Utils

The first line says where moxzi looked. A relative import is resolved from the importing file's directory, with .mo added. If the import is a package (mo:…), check that the package is in mops.toml and that you've run mops install. Run moxzi deps FILE to see which files the build can find.

Syntax error#

syntax.mo

actor {
  public func f() : async Nat {
    1
  };

Error: compilation failed:
/src/syntax.mo:5.1: syntax error [M0001], expected } (object body), got EOF

The location is where the parser gave up, which can be later than the actual mistake. Here the actor's closing }; is missing, and the parser reached the end of the file still looking for it.

Other errors you'll see often#

Code	Cause	Fix
`M0145`	A `switch` or `let` pattern doesn't cover every value, so it can trap	Add the missing cases, or pass `-W=M0145` to keep it a warning
`M0215`	A record has a field its type doesn't have, so the field is dropped	Remove the field, or pass `-W=M0215`
`M0031`	A public method takes or returns a function, mutable data or another non-shareable type	Use shareable types (records, variants, arrays of immutable data, `Text`, numbers, `Principal`) in public signatures
`M0035`, `M0041`	A public method doesn't return `async T` or `()`	Return `async T`
`M0069`	`actor { … }` inside a function or another expression	Move it to the top level, or use an `actor class`
`M0169`, `M0170`, `M0216`	An upgrade can't keep stable data	See Migrations
`M0250`, `M0254`, `M0267`	A problem in a migration chain	See Migration chains

Error codes lists every code.

Errors that mean a compiler bug#

Report these, with the file that caused them:

Output	Meaning
`[M9000] unimplemented: …`	The compiler reached a construct it doesn't support yet
`Error: canister trapped: …` with no file location	The compiler itself failed
A program that `moc` accepts fails to build, or the reverse	A compatibility bug

Reporting bugs says what to include.

Limitations#

Limitation	What to do
No long explanations (`moc --explain`)	Search for the code in the Motoko documentation
No JSON output (`moc --error-format json`)	Parse the `file:line.col-line.col: kind [code], message` lines
Some error messages show the compiler's internal type notation, such as `#Named("f", #Func(…))`	Compare with `moc`'s message for the same code