Atari BASIC Error Codes Explained: Causes and Fixes for Errors 2 to 171
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
