Atari BASIC Error Codes Explained: Causes and Fixes for Errors 2 to 171

Atari text screen listing five tests and their results: ERROR 3 at line 101, ERROR 5 at 102, ERROR 7 at 103, ERROR 18 at 104 and ERROR 20 at 105

Atari BASIC reports problems with a bare number: ERROR- 9 AT LINE 120. It does not say what the number means. The numbers fall into two groups. 2 to 21 come from BASIC itself. 128 and up come from the operating system's I/O routines (CIO and the device handlers) and from DOS, and BASIC simply passes them on. The same numbers appear in other languages and DOS menus, because they belong to the OS.

This reference lists them all, with the commonest real causes. For many we went further than the manuals: a test program deliberately triggered each error under TRAP on Atari BASIC revision C and recorded what came back. Those results are marked (tested).

What you need: nothing beyond Atari BASIC. To catch errors in your own programs, see Error Trapping in Atari BASIC.

Finding the number after the fact

After any error, or inside a TRAP routine:

900 E=PEEK(195):L=PEEK(186)+256*PEEK(187)
910 ? "ERROR ";E;" AT LINE ";L

Location 195 holds the last error number. Locations 186–187 hold the line where it happened.

BASIC errors (2–21)

No. Meaning Typical causes Fix
2 Memory insufficient DIMming more than the free memory (DIM A$(20000),B$(20000) with 37K free (tested)); GOSUBs that never RETURN; runaway recursion (102 GOSUB 102 (tested)) Check FRE(0); DIM smaller; leave subroutines by RETURN or POP (see Ram Cram)
3 Value error A value out of range for the statement: POKE 1536,256 (tested), SQR(-1) (tested), a negative line number such as GOTO X with X=−1 (tested) Check the range the statement accepts (0–255 for POKE values, and so on)
4 Too many variables A 129th variable name; names left over from editing count too LIST to disk, NEW, ENTER to clean out unused names; reuse variables
5 String length error Referring to character 0 or beyond the DIMmed size: D$(0)="X" (tested) String positions start at 1 and stop at the DIM size
6 Out of data READ after the last DATA item (tested) Count your items, or RESTORE before reading again
7 Value not a positive integer up to 32767 GOTO 40000 (tested); line numbers and some arguments above 32767 Keep line numbers and integer arguments within 0–32767
8 INPUT statement error Letters typed (or read from a file) into a numeric variable (tested with INPUT #) Input into a string and convert with VAL inside a TRAP
9 Array or string DIM error Using a string that was never DIMmed (Q$="X" (tested)); DIMming the same name twice (tested); a subscript outside the DIM; an array too large, such as DIM A(10000) (tested) DIM every string and array once, before use
10 Argument stack overflow An expression too complex for BASIC's evaluation stack Break the expression into steps
11 Floating-point overflow Division by zero (1/0 (tested)), results above about 1E+97 (1E+97*1E+97 (tested)) Guard divisors; scale your numbers
12 Line not found GOTO, GOSUB, THEN or ON to a missing line (GOTO 9999 (tested)) Check the target exists after renumbering or deleting
13 NEXT without FOR NEXT Q with no FOR Q (tested); a POP that removed the FOR Match every NEXT to a FOR; don't POP inside FOR loops
14 Line too long A line too long or complex to tokenize; with 20 nested parentheses BASIC refused the line on entry (tested) Split the line
15 GOSUB or FOR line deleted You deleted or changed a line holding an active FOR or GOSUB, then used CONT Type RUN again after editing
16 RETURN without GOSUB RETURN reached by falling into a subroutine (tested) Put END or GOTO before subroutines
17 Garbage (execution of bad data) Running a line that was stored with a syntax error. Such lines LIST as ERROR- and stop the program when reached (tested). Bad POKEs into the program area cause it too Retype the line; check POKE addresses
18 Invalid string character VAL("ABC"): the string does not start with a number (tested) Check input before VAL, or TRAP it
19 LOAD program too long The program needs more memory than is free, often because a DOS or handler now uses more low memory Boot with fewer drive buffers or no extra handlers
20 Bad device number IOCB number 0 or above 7: OPEN #8,... (tested) Use channels 1–5 (6 and 7 are used by BASIC)
21 LOAD file error LOADing something that is not a SAVEd BASIC program (tested) Use ENTER for LISTed text files and DOS's binary load for machine code

Two behaviours that are not errors, both tested: assigning a string longer than its DIM silently truncates it (D$="ABCDEFG" into a 5-character D$ gave "ABCDE"), and SOUND 0,256,10,8 was accepted without complaint.

I/O and DOS errors (128 and up)

No. Meaning Typical causes and fixes
128 BREAK abort BREAK was pressed during an I/O operation. TRAP it, or disable BREAK (see Reading the Keyboard)
129 IOCB already open OPEN on a channel that is still open (tested). Put CLOSE #n before each OPEN
130 Nonexistent device Unknown device letter (tested with Q:). Also D: when no DOS was booted, or R: before the 850 handler is loaded
131 IOCB write-only Reading from a channel opened for writing (tested)
132 Invalid command A command the handler does not recognise
133 Device or file not open PRINT #, GET # etc. on a channel never opened, or already closed (tested)
134 Bad IOCB number An illegal channel number passed to CIO
135 IOCB read-only Writing to a channel opened for reading. Open in mode 8, 9 or 12 instead
136 End of file Reading past the end of a file (tested). Normal at the end of a read loop; trap it
137 Truncated record A record longer than the buffer allows, typically one longer than 256 characters
138 Device timeout The device didn't answer: drive off or disconnected, wrong drive number, printer offline
139 Device NAK The device rejected the command: no disk in the drive, bad disk, wrong density
140 Serial bus input framing error Noise or a fault on the SIO cable, or a failing device
141 Cursor out of range POSITION outside the current mode's screen, then PRINT or PLOT (tested with POSITION 50,0)
142 Serial bus data frame overrun SIO data arriving too fast; a hardware or speed-setting problem
143 Serial bus checksum error Corrupted SIO transfer: check cables and drive health
144 Device done error Writing to a write-protected disk, a damaged sector, or a drive-reported failure
145 Read-after-write compare error The disk verify failed, or a bad screen mode was requested from S:
146 Function not implemented The handler can't do that: PUT to the keyboard (K:) (tested), an unknown XIO number (tested)
147 Insufficient RAM for graphics The GRAPHICS mode needs more memory than is free, often in a program that has DIMmed large arrays
150–154 850 / R: handler errors Port already open (150), concurrent mode not enabled (151), illegal user buffer (152), concurrent mode errors (153, 154). See The Atari 850 Interface Module
160 Drive number error A drive number DOS isn't set up for: raise the drive count in DOS, or use D1:
161 Too many open files More files open than DOS has buffers for (three by default in DOS 2.0S)
162 Disk full No free sectors
163 Unrecoverable system I/O error A DOS-level failure. Try another disk or drive
164 File number mismatch Broken sector links, or a POINT to a sector that isn't part of this file
165 File name error Bad name: up to eight letters or digits starting with a letter, plus an optional three-character extension
166 POINT data length error POINT to a byte beyond the sector's data
167 File locked Unlock it (DOS menu or XIO 36) before writing, renaming or deleting
168 Invalid command An XIO command DOS does not support
169 Directory full DOS 2 allows 64 files per disk
170 File not found Typo, wrong drive, or a missing extension (tested)
171 POINT invalid POINT to a position the file doesn't own

Our I/O tests used the emulator's H: host-folder device, which does not report every error a real drive would. Opening a file read-only and then writing to it, for example, did not produce 135 there. The meanings above for codes we could not trigger come from Atari's documentation.

A test harness you can reuse

The table above came from a loop like this. Each test line jumps back through the TRAP handler, so one RUN checks everything:

10 T=0:DIM D$(5):POKE 77,0
20 T=T+1:TRAP 900:ON T GOTO 101,102,103,104,105
30 END
101 POKE 1536,256:GOTO 950
102 D$(0)="X":GOTO 950
103 GOTO 40000
104 X=VAL("ABC"):GOTO 950
105 OPEN #8,4,0,"K:":GOTO 950
900 E=PEEK(195):? T;": ERROR ";E;" LINE ";PEEK(186)+256*PEEK(187):FOR K=1 TO 5:CLOSE #K:NEXT K:GOTO 20
950 ? T;": NO ERROR":GOTO 20

It prints 1: ERROR 3, 2: ERROR 5, 3: ERROR 7, 4: ERROR 18 and 5: ERROR 20. Note that TRAP must be set again after every error, which line 20 does on each pass. POKE 77,0 stops the attract mode from changing the screen colours while a long test runs.

Troubleshooting the troubleshooting

  • The error line number seems wrong: for errors inside a multi-statement line, the line number is right but the statement may be any of them. Split the line temporarily to find it.
  • ERROR 17 on a line you never touched: LIST it. If it reads ERROR-, it was typed (or ENTERed) with a syntax error and stored as-is. Retype it.
  • ERROR 9 straight after LOAD: a freshly loaded program has no strings or arrays DIMmed yet. Starting it with GOTO instead of RUN can skip the DIM statements at the top.
  • Error codes from other languages: the I/O numbers (128 up) mean the same thing in Atari Assembler, Action!, cc65 programs and DOS menus, because they come from CIO.

Further reading

  • Richard Haskell, Atari BASIC (Prentice-Hall), Appendix C: a compact table of all the error codes.
  • The Atari User's Encyclopedia (The Book Company, 1984): one-line explanations of every code.
  • Ian Chadwick, Mapping the Atari: locations 186–187 (STOPLN) and 195 (ERRSAVE).
  • On this site: Error Trapping in Atari BASIC, Working with Disk Files in Atari BASIC, CIO and IOCBs: How Atari Input/Output Really Works.

Credits

  • Picture: The test harness from this guide: each line triggers an error on purpose, and the TRAP handler reports PEEK(195) and the line. — Program authors; screenshot by the site
  • Mapping the Atari — 186-187 STOPLN, 195 ERRSAVE — AtariArchives.org