Next: Errors Up: Exceptions Previous: Exceptions

## 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.

Next: Errors Up: Exceptions Previous: Exceptions