64tass Troubleshooting: Common Errors and Fixes

64tass Troubleshooting: Common Errors and Fixes

Overview

This guide covers frequent problems when using 64tass (a 6502/65xx family assembler) and concise fixes to get your builds back on track.

1. “Unknown instruction” or “Illegal opcode”

• Cause: Typo in mnemonic, unsupported CPU mode, or using an instruction not available for the selected CPU.
• Fixes:
  1. Check spelling of the mnemonic.
  2. Specify the correct CPU in command line or source (e.g., –cpu 65c02) if using extended instructions.
  3. If targeting vanilla 6502, replace unsupported opcodes with equivalent sequences.

2. “Addressing mode not supported” or wrong operand size

• Cause: Using an addressing mode that doesn’t match the operand or CPU (e.g., trying absolute,X with a label outside zero page).
• Fixes:
  1. Confirm operand fits the chosen mode (zero page vs absolute).
  2. Force a mode explicitly using size suffixes or expressions (e.g., use LDA \(00</code> for zero page or <code class="qlv4I7skMF6Meluz0u8c wZ4JdaHxSAhGy1HoNVja _dJ357tkKXSh_Sup5xdW">LDA \)0100 for absolute).
  3. Switch CPU mode if you need a particular addressing feature.

3. “Expression too large” / constant overflow

• Cause: Immediate or branch displacement exceeds allowed range.
• Fixes:
  1. For branches, ensure target is within -128..+127 bytes; use a JMP (long branch) if out of range.
  2. For immediate operands, ensure values fit 8-bit or 16-bit constraints; mask or split larger values (.BYTE value & $FF).
  3. Use labels and compute offsets carefully; evaluate expressions with parentheses.

4. “Undefined symbol” or forward-reference errors

• Cause: Label referenced before it’s defined or missing symbol due to conditional assembly.
• Fixes:
  1. Ensure labels are defined; move or add the label before use where possible.
  2. Use = or .equ to define constants before use.
  3. If conditional assembly hides definitions, check .if / .else blocks and define fallback values.

5. “Duplicate symbol” or multiple definitions

• Cause: Same label or symbol defined more than once (across included files or multiple passes).
• Fixes:
  1. Rename conflicting symbols or convert duplicates to local labels (use numeric local labels or scope mechanisms).
  2. Use .global / .export intentionally and avoid exporting internal labels.
  3. Check included files and conditional blocks for accidental redefinitions.

6. Linker-related errors (wrong addresses, overlaps)

• Cause: ORG directives, segments, or linker settings place code/data where they overlap or conflict with ROM/RAM layout.
• Fixes:
  1. Verify .org values and segment assignments match your target memory map.
  2. Use labels and * (current location) carefully; inspect generated listing to confirm placements.