Diagnostics

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

Anatomy of a Diagnostic

Error [E1003]: undefined symbol `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 Levels.
• 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:

help: `nowhere_at_all` is defined outside this module. Use `@nowhere_at_all`

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.

Renumbered Codes

One number means one thing, and a code stands for one fault rather than a family. Two numbers each named two unrelated diagnostics and were told apart only by the level letter, so looking one up found whichever entry came first; four others covered several faults at once, so a [lint] entry or a search of a build log picked out a family rather than the fault meant.

Unused-Label Sweep

Syntax: fantasm build <source> -u

-u turns on that one sweep and nothing else. Every other warning is shown whether or not you pass it, and --no-find-unused turns off only the sweep. find_unused under [assembler] is the same setting in fantasm.toml.

fantasm build src/main.asm -u

[assembler]
find_unused = true

It was -W/--enable-warnings/--no-warnings and warnings until 2.0. Those still work, saying what replaced them once (W1103), and are withdrawn in 2.1.

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.

Nor for any part of a STRUCT instance something touches. An instance is one object’s layout, so a reference to a member marks the instance and vice versa: ld hl,inst and then indexing through (hl) uses every field without naming one. Deleting a member to answer a warning would move the fields after it, so there is no change to make. An instance nothing touches at all is still reported.

Common Codes

The elaboration below is present where the message alone leaves something unanswered. Every code is in Code Reference.

E1003 undefined symbol …

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. A missing file that is another target’s output is E1078 instead, which says so — see Building Several Images.

E1005 syntax error: …

The line stopped making sense. Where it can say more it adds it after the colon; a bare syntax error means there was nothing useful to name.

E1008 invalid instruction: …

A mnemonic that does not exist in the form you wrote it, or an operand the instruction cannot take.

E1013 … is already defined

The note points at the first definition.

E1016 Z80N instructions are not enabled

Set device = "zxnext", or z80n = true for a Z80N program on another machine. The hint says the same in directive form.

E1020 unknown assembler option …

The name after !opt. A value that option will not take is E1134, and an output format this build does not write is E1135; both name what is actually wrong rather than an option that was fine.

E1036 code size limit 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. The hint says which of the two limits was reached.

E1058 General error: …

Nothing in a source file raises it. It stood for a --test run’s failure count, an empty test body, a body with nowhere to go, a !rhai block missing its brace and two fantasm.toml target faults; those are E1138, E1139, E1140, E1005, E1141 and E1142.

E1060 … is a reserved word and cannot be a macro name

E1061 … is a reserved word and cannot be a macro parameter name

A macro’s name and its parameters cannot be words the tokeniser has already claimed — see Reserved Words. E1063 is the neighbouring case of a missing or malformed MODULE or !library name.

E1075 … is a string and cannot be used as a number

__NAME__ and friends carry text. Example: db __NAME__ assembles it, and ld a, __NAME__ is this.

W1068 code at … is in ROM on …

W1069 code at … assembled before the first ORG

Both usually mean a code-bearing INCLUDE sits above your ORG. Anything emitted before an origin lands at $0000.

E1200 Rhai function … failed: …

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’s name and its parameters must be words the tokeniser has not already claimed. Every word below produces a keyword token instead, so using one there raises E1060 or E1061.

Position decides everywhere else, and most slots take these words happily. A label may be named after any of them, and so may a STRUCT member, an ENUM member or type, a MODULE and a !library: org: is legal, KEEP org pins it, hex equ 9 defines a constant called hex, and Device db is a struct member. A register or condition name still cannot be a constant — a equ 5 is E1005.

assert and debug are in this table like any other directive, and like any other they can still name a label, a STRUCT member and the rest: DEBUG equ 1 with ld b,DEBUG and IFDEF DEBUG all work.

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

E1062 is withdrawn. It refused a module or library named after a reserved word, which is now allowed. device joined this table in 2.0 and costs a struct nothing, a member being read only as Type.member. target is here only while !target is still accepted, and leaves in 2.1.

⚠ 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.

Code Reference

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

← Documentation