Diagnostics

Every message FantASM prints carries a level, a code and a position.

Reading one

Error [E1003]: Undefined label or constant: `nowhere_at_all`
src/main.asm:12:6
  jp nowhere_at_all
     ^

• Error is the level.
• [E1003] is the level’s letter and the code. The letter matters — see below.
• src/main.asm:12:6 is file, line, column.
• The source line is quoted with a caret under the column, so you do not have to count.

Some diagnostics add more:

Hint: use @NAME to reach a constant outside this module

A hint says what to do about it. A note on a second location points at the other half of the problem — where a label was first defined, say, when you have defined it twice.

⛔ A diagnostic without a file:line is about the project file, not your source. The fault is in how fantasm.toml’s tables relate rather than at a point in any text, so there is no line to point at.

Levels

The same code number can carry different levels. 1012 is a warning when a value is truncated to 16 bits and an error when the same value cannot be used at all. The level is decided where the diagnostic is raised, which is why the letter is printed and not just the number.

One number, one meaning. 1049 and 1060 each named two unrelated diagnostics, told apart only by the level letter — so looking one up found whichever entry came first. The address error moved to 1082 and the NEX entry-point warning to 1083; the two numbers now mean what most people already thought they meant.

Asking for more warnings

-W turns on the unused-label sweep and nothing else. Every other warning is shown whether or not you pass it.

fantasm build src/main.asm -W

or in fantasm.toml:

[assembler]
warnings = true

W1049 unused label does not fire for a label that is KEEP-pinned, GLOBAL-exported, discarded by --gc-modules, or run into by the code above it — in none of those cases is there anything to act on.

Meeting the common ones

E1003 Undefined label or constant. A typo, a missing INCLUDE, or a name you expected to reach out of a MODULE. Constants do not fall back to global scope from inside a module — use @NAME.

E1004 File not found. Check include_dirs. If the missing file is another target’s output, you get E1078 instead, which is more useful — see Building Several Images.

E1005 Syntax error and E1008 Invalid instruction. Usually a mnemonic that does not exist in the form you wrote it, or an operand the instruction cannot take. Both quote what they found.

E1013 Attempt to redefine label or constant. The note points at the first definition.

E1016 Z80n extended instructions are not enabled. Set target = "zxnext", or z80n = true for a Z80N program on another machine.

E1036 Maximum code size exceeded. max_code_size limits how much code there is, not the address it reaches — a program ORGed at $8000 emitting 2 KB has used 2 KB of the budget. zx16 additionally refuses anything above $8000.

W1068 Code emitted in ROM and W1069 Code assembled before any ORG. Both usually mean a code-bearing INCLUDE sits above your ORG. Anything emitted before an origin lands at $0000.

E1060–E1063 Reserved word. A macro name, macro parameter or module name cannot be a word the tokeniser has already claimed — see below.

E1075 This is a string, which has no numeric value. __NAME__ and friends carry text. db __NAME__ assembles it; ld a, __NAME__ cannot.

E1200 Rhai error. A !rhai block failed to compile, or the engine ran into a fault. The position points inside the script, at the line you wrote rather than at the !rhai that opened it. What a script says on purpose — ctx.warn, ctx.error — is 1080 instead, in the script’s own words.

Reserved words

A macro name, a macro parameter name and a module name must be words the tokeniser has not already claimed. Every word below produces a keyword token instead, so using one raises E1060, E1061 or E1062.

A label may be named after any of these, and a constant after a directive: org: is legal, KEEP org pins it, and hex equ 9 defines a constant called hex. A register or condition name cannot be a constant — a equ 5 is E1005.

Matching is case-insensitive, so Slot and SLOT are reserved too.

⛔ This is the first thing to check when a name behaves strangely. A module called A or a macro parameter called c is a register name, and the diagnostic that results rarely mentions registers. It costs nothing to rule out and saves a long search when it is the cause.

Every code

The message text is what FantASM prints; … stands for a name, file or value it fills in.

← Documentation