A Guide to Atari Error Codes

by Steve Pedler


Issue 21

May/Jun 86

Next Article >>

<< Prev Article



As everyone should know, when an error occurs during the running of a BASIC program, a code is returned to the user indicating the type of error that has taken place. Unfortunately, you then have to look up the meaning of these codes in a manual, and the explanations are all too often very brief and written in a kind of Atarispeak which may be difficult if not impossible to interpret. A better explanation of these codes might not come amiss and I therefore present a guide to the meaning of ATARI Error codes, why they occur and how to avoid them.

In this guide I give the error codes followed by the 'official' name as found in the Atari BASIC Reference Manual appendix B). Note that error names may vary between different publications (even Atari publications!) as may the explanations given.

For further information, see the following sources:

Atari BASIC Reference Manual (Atari Inc.)
Technical Reference Notes (Atari Inc.)
DOS 3 Reference Manual (Atari Inc.)
Your Atari Computer (Osborne-McGraw Hill)

Revised Mapping the Atari (Compute! Books)

Part 1 - Language specific errors.

Errors 2 - 21 only occur when a BASIC program is running. Other languages (e.g. the Assembler-Editor cartridge) also use these numbers, but have a completely different meaning. You should also note that errors occurring during the execution from BASIC of machine language subroutines may generate error codes which bear no relation to the error which actually occurred.


There is in fact no 'error' 1 in Atari BASIC. The value is returned by the operating system on successful completion of an input-output (I/O) operation. Quite properly, BASIC doesn't bother telling you this, but just gets on with the job.

Error-2 Memory insufficient.

During the running of a program, BASIC maintains a series of pointers in RAM to keep track of memory usage. Two of these are MEMTOP (locations 741,742) and APPMHI (14,15). MEMTOP is a pointer to the top of free memory. Above the location found in MEMTOP is the display list, and following that the screen RAM. The value in MEMTOP is moved up or down depending on the graphics mode selected, the greater the memory requirement for any mode, the lower is the value contained here. APPMHI is a pointer to the top of your BASIC program. Whenever a new line is added to the program, or when space is reserved for a string or array by the DIM statement, the value in APPMHI is increased. If, either during the typing in of a program or during a run, the value in APPMHI is greater than that in MEMTOP, error 2 is the result. (There is an exception - see error 147).

This error may also occur if RAMTOP (106), the pointer to the top of available memory, is moved down
too far, since this will also cause MEMTOP to be lowered when the graphics mode is changed. This could occur during repeated runs of a program which deliberately lowers RAMTOP (e.g. during debugging). To avoid this, press Reset before re-running such a program.

Error-3 Value error.

This is a common error which can be surprisingly difficult to track down. It occurs when attempting to use a number whose value is in some way unacceptable to the computer. Trying to POKE a memory location with a negative number or one greater than 255 will cause this problem. So too will trying to access part of a string or array with a negative index value, or if the second index is smaller than the first. For example, the following lines would generate this error:

10 DIM A$(9):? A$(7,1) 

20 END

On the face of it this should be easily avoidable. However, frequently a program first computes the value of a variable then uses the variable in a POKE statement or as a string or array index. It is all too easy during the initial computation to obtain a value that is not acceptable to the machine. If the cause of this error is not clear, check the actual value of your variables against what you think they should be.

Error-4 Too many variables.

Atari BASIC only allows you the use of 128 different variable names. In practice, this should be enough for most applications, so that you are unlikely to see this error. One point to beware of is that variables used during program development, but not in the final version, will remain in BASIC's variable name table even if no longer used in the program. If you are running short of variables, you can clear out the unwanted ones by LISTing your program to cassette or disk, typing NEW (which clears the variable name table) and ENTERing your program again.

Why does this limitation exist? When a BASIC program is present in memory (or SAVEd to cassette or disk) it is in tokenised form rather than full ATASCII format. Each BASIC keyword is stored as a one byte token, so that (for example) the word RESTORE is stored as one byte rather than seven (one for each character). Variables are also stored as tokens, so that no matter how long the variable name, it still only takes up one byte each time it occurs in the program. One byte can only contain 256 different numbers, the BASIC keywords are allocated numbers 0-127 (though not all are used) leaving the numbers 128-255 for the variables - giving 128 different names.

Should you need more than 128 variables, then you can store numeric variables as elements of an array. For example, the statement DIM ARRAY(99) will set up an array of 100 elements. Each of these elements can hold a different number, but the array still only takes up one variable name.

Error-5 String length error.

Whenever you use a string, you must first tell the machine how long you want the string to be, using the DIM statement. BASIC then reserves a section of memory to contain the contents of your string. The convention used is that the first character of the string is given the index value 1 (i.e. PRINT A$(1,1) would print the first character of A$). If you use zero as an index, then error 5 occurs. Incidentally, note that just to be confusing, the first element of an array is given an index of zero!

This error will also occur if you use an index value greater than the dimensioned string length. If you need a longer string, you will have to alter the original DIM statement. Once again, it is easy to cause this error when using variables as string indices. See also errors 3 and 9.

Error-6 Out of data error.

Whenever you use the READ statement, BASIC obediently tries to read as many items of DATA as you have instructed. Every time one piece of data is read, a pointer is updated to point to the next piece. If BASIC finds that there is no more data in the program, but it is still under orders to READ, then the run stops and error 6 is returned (but see below). This error is usually caused by miscounting the number of data items to be read (often by means of a FOR ... NEXT loop) or by missing out one or more pieces of data. A slightly more obscure cause is that the pointer is not moved during a GOSUB...RETURN loop. If your subroutine reads data contained in lines which are part of the subroutine itself, and control then returns to the main program, when you next try to read data the pointer will be pointing to data lines following the subroutine (if any). To avoid this, you should make appropriate use of the RESTORE statement.

You can make use of this error in your programs. If you have large amounts of data to read in, then rather than count them all up, you simply set a TRAP to the line where the program is to continue when all DATA is read. You then set up a simple loop which forces BASIC to read data until there is none left, at which point error 6 occurs but is caught by the TRAP and the program then continues as normal.

Error-7 Number greater than 32767.

Theoretically this error means that you have used a number greater than 32767 (hex $7FFF) where this is not acceptable to the machine. In practice, the only reason I know for this error is a line number larger than 32767 - and I'm not sure why this limit exists. Does anyone else have any further information?

If you try to type in a line with a line number of 32768 or more, you simply get a syntax error on pressing Return. However, Atari BASIC allows you to use variables as line numbers in statements such as GOTO, GOSUB etc. so look out for the possibility that the variable is larger than the allowed limit.

Error-8 Input statement error.

When you issue an INPUT statement, BASIC expects the program to enter an appropriate reply, (either via the keyboard or from cassette or disk) which will either be a number or a character string. While it is quite acceptable to enter numbers in response to a string input request (the characters making up the number are treated just like any other string) it is not acceptable to enter a string when BASIC expects a number. This is because BASIC will try to assign the number which is input to a variable (e.g. if you respond with '450' to the statement 'INPUT A', the variable A gets the value 450). It clearly can't do this with a string of characters, and so will generate this error. Pressing Return without entering any number at all will also cause the error.

You can prevent users crashing your programs in this manner by setting a TRAP so that any input which generates an error could print a message and a request to try again.

Error-9 Array or string DIM error.

There are three possible causes of this error.

i) As mentioned above, in Atari BASIC you must DIMension all strings or arrays before use. If this is not done, and you try to use an undimensioned string or array, this error results.

ii) You may also only dimension a string or array once per program run. A good practice would be to contain your initialization code (including setting up strings and arrays in a separate subroutine called only once at the start of the program. This will prevent accidental redimension of your strings. Should you for some reason need to redimension strings or arrays during a program you must use the CLR statement to undimension them first.

iii) There is an absolute limitation of dimension size of 32767 for strings, and 5460 for arrays. Exceeding this limit will generate error 9. Different strings or arrays when combined may however exceed this limit, providing you don't exceed available memory, in which case you will get error 2. (The odd looking figure of 5460 for array size comes about because DIMensioning an array to this size sets up the array to hold 5461 elements. Since each element takes up six bytes, and 5461 x 6 = 32766, one more element would exceed the 32767 limit

Error-10 Argument stack overflow.

As BASIC processes a program line, if it comes across an arithmetical expression it first places the various arithmetical operators it finds on an 'operator stack'. The order in which the operators go on the stack is of some importance, since it determines the order in which BASIC carries them out. In some cases the order depends on priority (multiplication has priority over addition, for example), otherwise on the order they occurred in the statement. This order can be specifically overridden by using parentheses. The size of the stack is limited. If the number of operators or the number of parentheses cause the stack size to be exceeded (stack overflow), error 10 is returned. If this occurs, you will have to simplify the offending expression.

Error-11 Floating point overflow/underflow error.

BASIC stores numbers in your program in a 'floating point' format, using six bytes every time a number occurs. (It is clearly more economical of memory to assign a variable to a number if you intend to use that number frequently, since this will only use one byte every time it occurs.) By using this format, BASIC can utilise numbers as large as 10 to the power 98, or as small as 1 divided by 10 to power 99 (should be a good enough range for most purposes!). If you exceed these limits, then BASIC can't handle it, and this error results. The usual cause of this is inadvertently dividing a number by zero (the theoretical result of which is infinity).

Error-12 Line not found.

Certain keywords in BASIC are followed by a line number, e.g. GOTO, GOSUB, etc. When such a statement is processed, BASIC attempts to find the indicated line. If it can't do so, then it literally has nowhere to go, so the run stops and this error is returned. 

There is an interesting feature here to do with the TRAP statement. If you set a trap to a nonexistent line number, and an error occurs to spring the trap, then instead of error 12, as you might expect, you get the error which sprung the trap in the first place. You can use this to clear previously set traps which are no longer wanted, by setting the trap to a line known not to exist).

Error-13 No matching FOR statement.

On processing a FOR statement, BASIC puts 16 bytes into an area of memory called the run-time stack. This is in RAM, pointed to by locations 142 and 143, and is situated directly above the string/array area (itself just above the main body of the program). The first 12 bytes are the numerical limit the variable can reach then the step increase or decrease (six bytes per number in floating-point format). The remaining four bytes are the variable number as it occurs in the variable name table, the line number where the FOR occurs, and the offset into that line. When it reaches the corresponding NEXT, BASIC checks that the variable limit is not yet reached, and then returns to the line containing the FOR. Clearly, if BASIC finds a NEXT without a corresponding FOR, there is nothing on the run-time stack to indicate the point of return, and program execution must stop.

GOSUB statements also use the run-time stack, placing four bytes on it. These are an identifier byte to indicate a GOSUB, the line number to go back to on reaching the RETURN statement, and the offset into that line. See the description of error 16.

This error also occurs if your FOR ... NEXT loops have not been properly nested. If the variable in the NEXT statement is not the same as that in the FOR entry on the stack, then the same problem arises.

Error-14 Line too long error.

When you type in a line of code and press Return, your line goes into BASIC's input buffer, 128 bytes located from 1408 to 1535 (580-5FF hex). BASIC then proceeds to tokenise the line (see error 4 above for an explanation of tokenising) and puts the resulting tokens into its output buffer, 256 bytes of RAM located above the value contained in MEMLO (743, 744). If the length of the tokenised line exceeds 256 bytes during the tokenising process, error 14 occurs. It's not very likely, but if it does happen you will have to shorten the line.

Error-15 GOSUB or FOR line deleted.

This is a strange error which I have never actually seen m practice. You will remember (see error 13 above) that GOSUB and FOR statements use the run-time stack to indicate the line to which control should pass on reaching the RETURN or NEXT statement. This error means that on reaching a RETURN (or NEXT) BASIC fetches a line number from the run-time stack, but cannot then find that line. This in turn implies that the line was deleted between BASIC's encountering the GOSUB (or FOR) and the RETURN (or NEXT). It is difficult to think of circumstances in which this might occur, but it is possible that POKEing around in the area of RAM which contains the program might alter line numbers. Another possibility is faulty RAM, causing program lines to be lost.

Error-16 RETURN error.

This error is analogous to error 13 above. On reaching a RETURN, BASIC gets the line number to return to (and the offset into that line) from the run-time stack. If a RETURN is reached before a GOSUB, there won't be an entry on the stack and program execution will have to stop.

Error-17 Garbage error.

A very reassuring error message to get! What it means is that while executing the program, BASIC has come across a line which contains non-executable (garbage) code. There are several possible reasons. Although Atari BASIC performs syntax checking on entry of program lines, it is quite easy (especially if you are in a hurry) to miss the syntax error display you normally get. This erroneous line will however be entered into memory (at least in part), and when BASIC finds it again error 17 is the result. It is also likely that POKEing directly into the RAM containing your program would alter the code, causing havoc at run time. The third possibility (least likely of all) is that your RAM might be at fault.

Error-18 Invalid string character.

This error relates to the use of the VAL function. Although numbers are usually held as constants or as numeric variables, it is possible to store numbers as strings. To convert a number to a string, you use the STR$ function. You can then perform string handling operations on the result. To convert the string back into a number for arithmetical operations, VAL is used. VAL can only be used however if the string is composed of numbers, or (at the least) if the first character of the string is a number. If this condition is not met, this error is generated.

Error-19 LOAD program too long. 

This error is a very simple, one: it means that the program you are trying to LOAD is too large to fit into the available RAM. This is not likely-to be seen with today's 48K-plus machines, but it must have been fairly common in the days of the 8K Ataris. There is no easy solution; if this happens, you will have to install some more memory in your computer. It is possible that this error might occur in a 48K machine with faulty RAM.

Error-20 Device number error.

This error occurs during input/output operations if you try to use an incorrect IOCB (channel) number. (See error 134 in the second part of this article for a brief explanation of IOCBs.) The Atari can use up to eight IOCBs (numbered 0-7) for communication with peripherals, but BASIC reserves IOCB zero for its own use. The IOCB number is the number following the 'hash' sign in statements such as PRINT #6, OPEN #1, CLOSE #7, etc. and must be numbered from one to seven inclusive. See also error 134.

Error-21 LOAD file error.

When you try to LOAD (or CLOAD) a program, the computer expects to receive a BASIC program in tokenised format (see error 4 for an explanation of tokenising). Tokenised BASIC programs are only stored on cassette or disk with the SAVE (or CSAVE) command, and files created by any other means will not be in this form. Trying to LOAD anything other than a tokenised BASIC program will produce error 21. Examples of such files would include any file LISTed to cassette or disk (full ATASCII format), machine language programs, screen memory dumps etc.

If this error occurs, you will have to use the correct command to reload your file. For example, this would be ENTER for LISTed files, the DOS binary load option L for machine code files, and so on.

Next issue - Steve Pedler concludes this article with a comprehensive look at the Error codes associated with INPUT/OUTPUT and the Operating System.