Primitive Exceptions

Whenever a primitive error occurs in MzScheme, an exception is raised. The value that is passed to the current exception handler is always an instance of the exn structure type. Every exn structure value has a message field that is a string, the primitive error message. The default exception handler recognizes exception values with the exn? predicate and passes the error message to the current error display handler (see error-display-handler in section 9.4.1.9).

Primitive errors do not create immediate instances of the exn structure type. Instead, an instance from a hierarchy of subtypes of exn is instantiated. The subtype more precisely identifies the error that occurred and may contain additional information about the error. The table below defines the type hierarchy that is used by primitive errors and matches each subtype with the primitive errors that instantiate it.

In the table, each bulleted line is a separate structure type. A type is nested under another when it is a subtype. The full name of the structure type (as used by predicates and selectors in the global environment) is built by combining the full name of the immediate supertype with ``:'' and the subtype name.

For example, applying a procedure to the wrong number of arguments raises an exception as an instance of exn:application:arity. An exception handler can test for this kind of exception using the global exn:application:arity? predicate. Given such an exception, the (incorrect) number of arguments provided is obtained from the exception with exn:application-value, while exn:application:arity-expected accesses the actual arity of the procedure.

      exn : not instantiated directly 
            fields:  message -- error message (type: immutable-string) 
                     continuation-marks -- value returned by current-continuation-marks immediately after the error is detected (type: mark-set) 
            user : raised by calling error 
            variable : unbound global variable at run-time 
                  fields:  id -- the unbound variable's global identifier (type: symbol) 
                  keyword : attempt to change the binding of a global keyword 
            application : not instantiated directly 
                  fields:  value -- the error-specific inappropriate value (type: value) 
                  arity : application with the wrong number of arguments 
                        fields:  expected -- the correct procedure arity as returned by arity (type: arity) 
                  type : wrong argument type to a procedure, not including divide-by-zero 
                        fields:  expected -- name of the expected type (type: symbol) 
                  mismatch : bad argument combination (e.g., out-of-range index for a vector) or platform-specific integer range error 
                  divide-by-zero : divide by zero; application-value is always zero 
                  continuation : attempt to cross a continuation boundary or apply another thread's continuation 
            else : fall-through in cond or case 
            struct : the supertype expression in a struct form returned a value that was not a structure type value 
            object : object-, class-, or interface-specific error 
            unit : unit- or unit/sig-specific error 
            syntax : syntax error, but not a read error 
                  fields:  expr -- illegal expression (or #f if unknown) (type: S-expression) 
            read : read parsing error 
                  fields:  port -- port being read (type: input-port) 
                  eof : unexpected end-of-file 
            i/o : not instantiated directly 
                  port : not instantiated directly 
                        fields:  port -- port for attempted operation (type: port) 
                        read : error reading from a port 
                        write : error writing to a port 
                        closed : attempt to operate on a closed port 
                        user : user-defined input port returned a non-character from the character-getting procedure 
                  filesystem : illegal pathname or error manipulating a filesystem object 
                        fields:  pathname -- file or directory pathname (type: path) 
                                 detail -- 'ill-formed-path, 'already-exists, or 'wrong-version, indicating the reason for the exception (if available), or #f (type: symbol or false) 
                  tcp : TCP errors 
            thread : raised by call-with-custodian 
            misc : low-level or MzScheme-specific error 
                  unsupported : unsupported feature 
                  user-break : asynchronous thread break 
                        fields:  continuation -- a continuation that resumes from the break (type: continuation) 
                  out-of-memory : out of memory

Primitive procedures that accept a procedure argument with a particular required arity (e.g., call-with-input-file, call/cc) check the argument's arity immediately, raising exn:application:type if the arity is incorrect.