Diagnostics

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

Anatomy of a Diagnostic

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.

A code that stood for several faults now stands for one. 1020 covered a bad option name, a bad option value and an unknown output format; 1058 covered five things at once. Each has its own code, so a [lint] entry or a search of a build log picks out the fault you mean rather than its family. The splits are 1020 → 1129, 1130, 1134, 1135; 1008 and 1005 → 1136, 1137; and 1058 → 1005, 1138, 1139, 1140, 1141, 1142.

The Unused-Label Sweep

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

fantasm build src/main.asm -u

or in fantasm.toml:

[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

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. Where either can say more it adds it after a colon; a bare Syntax error means the line stopped making sense and there was nothing useful to name.

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

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

E1020 … is not an 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.

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.

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, E1061 Reserved word. A macro’s name and a macro’s parameters cannot be words the tokeniser has already claimed — see below. E1063 is the neighbouring case of a missing or malformed MODULE or !library name.

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

⚠ E1062 is withdrawn. It refused a module or library named after a reserved word, which is now allowed.

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

⚠ device joined this table in 2.0, and costs a struct nothing: a member may be named after any reserved word, 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.

The Full Reference

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

← Documentation