Errors

The index for the Allegro CL Documentation is in index.htm. The documentation is described in introduction.htm.

This document contains the following sections:

1.0 Errors
   1.1 More on cl:stream-error
2.0 Some common errors
   2.1 An unhandled error occurred during initialization:
   2.2 Attempt to call -name- which is defined as a macro
   2.3 Gc errors
   2.4 Bus errors and segmentation violations
   2.5 Using package [package] results in name conflicts...
3.0 Type errors in sequence functions

1.0 Errors

Errors in Allegro CL are handled by the condition system as described in the ANSI spec. Note too that some errors in Allegro CL are still classified as simple-errors when they should be classified otherwise.

The errorset macro is preserved from earlier versions of Allegro CL although its functionality is completely superceded by the condition system. It is maintained for backward compatibility and its use in newly written code is not recommended.

Here is the condition type hierarchy. Allegro CL has some additional error types defined. They are marked with an *. The ones with links are further described. You can get the condition object associated with an error with the top-level command :error, which, besides printing the error message sets the value of * to the condition object.

  condition
  advance-warning *
  input-edit *
  ics-dependent-classa *
  ics-dependent-classb *
  compiler-note *
  serious-condition
    storage-condition
    error
      type-error
        case-failure *
        simple-type-error
      stream-errorstream-closed-error *
        end-of-file
        reader-error (also subclass of parse-error)
        socket-error *
        errno-stream-error *
      parse-error
        reader-error (also subclass of stream-error)
      operating-system-signal *
        synchronous-operating-system-signal *
        asynchronous-operating-system-signal *
          interrupt-signal *
      package-error
        package-locked-error *
      file-error
      cell-error
        unbound-slot
        undefined-function
        unbound-variable
      print-not-readable
      arithmetic-error
        floating-point-inexact
        floating-point-invalid-operation
        floating-point-underflow [see note after table]
        floating-point-overflow
        division-by-zero
      compiler-not-available-error *
      program-error
      control-error
      simple-error
      socket-error *
  break
    simple-break *
  warning
    compiler-not-available-warning *
    simple-warning
    style-warning
      ineffective-declaration-warning *
         float-declaration-used-warning *
      compiler-undefined-functions-called-warning *
      compiler-no-in-package-warning *
  simple-condition
    simple-type-error
    simple-error
    simple-break *
    simple-warning

Table Notes

floating-point-underflow is not usually signaled because most operating systems silently replace an underflow with zero without further action.

1.1 More on cl:stream-error

The stream-error class, as implemented in Allegro CL, has these slots:

stream: the stream which got the error. This is the standard CL slot and is accessed by stream-error-stream.
action: the action that was being attempted at the time of the error, accessed by stream-error-action.
code: the errno code returned from the system, nil if none. Accessed by stream-error-code.
identifier: symbolic identification of the code, or nil if unknown. Accessed by stream-error-identifier.

With the new stream-error conditions and slots, Allegro CL classifies stream error situations when possible, relying on a catch-all condition to hold errno returns that could not be classified. A user might want to do handler-binds on the condition subclasses, or on the stream-error condition and then test the identifier slot. All stream conditions have such an identifier slot, but some conditions (especially the catch-all errno-stream-error condiion) may not fill it in.

In paticular, when a system operation returns an errno value, it is looked up to see if it is a socket-error, and if so, a socket-error condition is created. It is intended then that other errno classifications will be tried (but note Allegro CL 6.0 initially has no others, but it is possible that during 6.0 patch process other condition subclasses will be added). If no classification can be made, then an errno-stream-error condition is created. Its identifier slot is set to :unknown, but an attempt is made to find out from the operating system what the string for such an error is, and that is stored into the condition in the string slot, for easier human identification.

2.0 Some common errors

We list here some common error messages. This list is by no means exhaustive and we only give a brief description of the likely cause. Error messages start with Error:, but we leave that out here. Names (of functions, symbols, etc.) that appear in error messages are replaced with [name] or some other generic placeholder.

2.1 An unhandled error occurred during initialization:

This is printed when an error occurrs while Lisp was running through its startup procedure. [message] is the error message generated by the actual error. The startup fails as a result of the error. Assuming the startup procedure has not been changed, these cannot be the cause of this error:

Reading an initialization (.clinit.cl, clinit.cl or the sys:siteinit.cl) file. If an error reading one of these files is encountered, the error is reported and further reading of the file is aborted, but otherwise the error is ignored.
Inability to find a loaded .so/.sl/.dll file. A warning but no error is signaled if the file cannot be found. Note that an error might be caused if a foreign function whose code resides in the missing .so file is called during startup.
A problem with *restart-init-function* or *restart-app-function*. These functions are called outside the handler which prints the An unhandled error ... message.

These may be the cause:

An error evaluating a -e [form] command-line argument. Try to start without the -e arguments.
An error performing the *restart-actions*. Try to start with the following on the command line (it suppresses any restart actions). Be sure to wrap the parentheses with ' marks or other shell-specific quotation-like marks. -e (setq excl:*restart-actions* nil)
An error evaluating the form that is the value of the ACL_STARTUP_HOOK environment variable. Try restarting after unsetenv'ing that variable.

2.2 Attempt to call -name- which is defined as a macro

Code calling [name] was compiled before [name] was defined as a macro is the cause.

user(1): (defun foo () (bar) 10)
foo
user(2): (compile *)
Warning: While compiling these undefined functions were referenced: bar.
foo
nil
nil
user(3): (defmacro bar nil nil)
bar
user(4): (foo)
Error: Attempt to call bar which is defined as a macro.
   [condition type: program-error]
[1] user(5):

The example above shows the definitions typed to the top-level, but this error is most commonly caused when files are compiled in the wrong order.

2.3 Gc errors

See gc errors in gc.htm where these errors are discussed.

2.4 Bus errors and segmentation violations

Bus errors and segmentation violations are standard OS errors. They are not specific to Lisp. Typically, a bus error is caused by an attempt to write to read-only memory while a segmentation violation is an attempt to access memory that does not exist. You may see them signaled in Lisp, usually when an error is signaled from code compiled at high speed and low safety (so standard Lisp error checkers are not used). If you see such an error, try recompiling code at higher safety and lower speed (in particular, make trust-declarations-switch return nil) and see whether the error persists.

2.5 Using package [package] results in name conflicts...

Suppose you try to call a function in a currently-unused package but forget the package qualifier. For example, suppose you called process-run-function without the mp: and the multiprocessing package is not used. You get an error about process-run-function not having a function definition (as expected). Then you use the multiprocessing package by evaluating (use-package :mp). The following error will be signaled:

Error: Using package `MULTIPROCESSING' results in name conflicts for these
symbols: PROCESS-RUN-FUNCTION [condition type: PACKAGE-ERROR] 
Restart actions (select using :continue): 
  0: Unintern the conflicting symbols in the `MULTIPROCESSING' package.

In order for process-run-function typed without a package qualifier to be process-run-function, enter

:continue 0

The message is confusing but that is the right choice.

3.0 Type errors in sequence functions

Many Common Lisp sequence function are sensitive to the type of their arguments. Consider the following incorrect forms:

(make-list nil)  ;; argument should be an integer. NIL is illegal
(elt #(1 2 3) nil) ;; second argument should be an integer. 
                   ;; NIL is illegal
(mapcar #'alpha-char-p "N ")  ;; second argument should be a list
                              ;; not a string

In each case, the argument given is wrong, but not unreasonable, and a programmer could carelessly but understandably make the errors shown (indeed, all these errors come from our support files). But note they reached our support files because the result (in earlier releases of Allegro CL) of evaluating the erroneous form was more serious than expected: rather than simply signaling an error, Lisp would in some cases enter an infinite loop and have to be interrupted.

In safe code, sequence functions such as the ones above should check that their arguments are of the correct type and signal a type error if they are not. But there is always a price to pay for argument checking: it consumes machine cycles in every call to a function in order to weed out erroneous code.

Starting in release 6.0, Allegro CL has two sequence function modules: :safeseq and :fastseq. Either two can be require'd at any time, and they each cancel the effect of the other. These modules hold the safe or fast run-time definitions of several problematic sequence functions that are hard to decide how to balance between safety and speed.

Thus, to use safe sequence functions, evaluate at any time:

(require :safeseq)

And to use fast (but without argument checking) sequence functions, evaluate at any time:

(require :fastseq)

It should be noted that functions in the :safeseq module are not better per se than those in :fastseq, and for correct code each module's functions operate correctly. Rather, the functions in :safeseq behave better with improper arguments.

The current list of functions which are affected by these modules include (but are not limited to, possibly by indirection): elt, length, make-list, all of the map functions, e.g. mapc, mapcar, etc., and butlast.