On this page:
9.2.1 Raising Exceptions
raise
error
raise-user-error
raise-type-error
raise-mismatch-error
raise-arity-error
raise-syntax-error
9.2.2 Handling Exceptions
call-with-exception-handler
uncaught-exception-handler
with-handlers
with-handlers*
9.2.3 Configuring Default Handling
error-escape-handler
error-display-handler
error-print-width
error-print-context-length
error-value->string-handler
error-print-source-location
9.2.4 Built-in Exception Types
exn
exn: fail
exn: fail: contract
exn: fail: contract: arity
exn: fail: contract: divide-by-zero
exn: fail: contract: non-fixnum-result
exn: fail: contract: continuation
exn: fail: contract: variable
exn: fail: syntax
exn: fail: syntax: unbound
exn: fail: read
exn: fail: read: eof
exn: fail: read: non-char
exn: fail: filesystem
exn: fail: filesystem: exists
exn: fail: filesystem: version
exn: fail: network
exn: fail: out-of-memory
exn: fail: unsupported
exn: fail: user
exn: break
prop: exn: srclocs
exn: srclocs?
exn: srclocs-accessor
srcloc

9.2 Exceptions

See Exceptions for information on the Racket exception model. It is based on a proposal by Friedman, Haynes, and Dybvig [Friedman95].

Whenever a primitive error occurs in Racket, an exception is raised. The value that is passed to the current exception handler for a primitive error 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).

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:fail:contract if the arity is incorrect.

9.2.1 Raising Exceptions

(raise v [barrier?])  any
  v : any/c
  barrier? : any/c = #t
Raises an exception, where v represents the exception being raised. The v argument can be anything; it is passed to the current exception handler.

If barrier? is true, then the call to the exception handler is protected by a continuation barrier, so that multiple returns/escapes are impossible. All exceptions raised by racket functions effectively use raise with a #t value for barrier?.

Breaks are disabled from the time the exception is raised until the exception handler obtains control, and the handler itself is parameterize-breaked to disable breaks initially; see Breaks for more information on breaks.

Examples:

> (with-handlers ([number? (lambda (n)
                             (+ n 5))])
    (raise 18 #t))

23

> (define-struct (my-exception exn:fail:user) ())
> (with-handlers ([my-exception? (lambda (e)
                                   #f)])
    (+ 5 (raise (make-my-exception
                  "failed"
                  (current-continuation-marks)))))

#f

> (raise 'failed #t)

uncaught exception: failed

(error sym)  any
  sym : symbol?
(error msg v ...)  any
  msg : string?
  v : any/c
(error src frmat v ...)  any
  src : symbol?
  frmat : string?
  v : any/c
Raises the exception exn:fail, which contains an error string. The different forms produce the error string in different ways:

In all cases, the constructed message string is passed to make-exn:fail, and the resulting exception is raised.

Examples:

> (error 'failed)

error: failed

> (error "failed" 23 'pizza (list 1 2 3))

failed 23 pizza (1 2 3)

> (error 'method-a "failed because ~a" "no argument supplied")

method-a: failed because no argument supplied

(raise-user-error sym)  any
  sym : symbol?
(raise-user-error msg v ...)  any
  msg : string?
  v : any/c
(raise-user-error src format v ...)  any
  src : symbol?
  format : string?
  v : any/c
Like error, but constructs an exception with make-exn:fail:user instead of make-exn:fail. The default error display handler does not show a “stack trace” for exn:fail:user exceptions (see Continuation Marks), so raise-user-error should be used for errors that are intended for end users.

Examples:

> (raise-user-error 'failed)

error: failed

> (raise-user-error "failed" 23 'pizza (list 1 2 3))

failed 23 pizza (1 2 3)

> (raise-user-error 'method-a "failed because ~a" "no argument supplied")

method-a: failed because no argument supplied

(raise-type-error name expected v)  any
  name : symbol?
  expected : string?
  v : any/c
(raise-type-error name expected bad-pos v ...)  any
  name : symbol?
  expected : string?
  bad-pos : exact-nonnegative-integer?
  v : any/c
Creates an exn:fail:contract value and raises it as an exception. The name argument is used as the source procedure’s name in the error message. The expected argument is used as a description of the expected type.

In the first form, v is the value received by the procedure that does not have the expected type.

In the second form, the bad argument is indicated by an index bad-pos (counting from 0), and all of the original arguments v are provided (in order). The resulting error message names the bad argument and also lists the other arguments. If bad-pos is not less than the number of vs, the exn:fail:contract exception is raised.

Examples:

> (define (feed-cow animal)
    (if (not (eq? animal 'cow))
      (raise-type-error 'feed-cow "cow" animal)
      "fed the cow"))
> (feed-cow 'turkey)

feed-cow: expected argument of type <cow>; given 'turkey

> (define (feed-animals cow sheep goose cat)
    (if (not (eq? goose 'goose))
      (raise-type-error 'feed-animals "goose" 2 cow sheep goose cat)
      "fed the animals"))
> (feed-animals 'cow 'sheep 'dog 'cat)

feed-animals: expects type <goose> as 3rd argument, given:

'dog; other arguments were: 'cow 'sheep 'cat

(raise-mismatch-error name    
  message    
  v ...+    
  ...+)  any
  name : symbol?
  message : string?
  v : any/c
Creates an exn:fail:contract value and raises it as an exception. The name is used as the source procedure’s name in the error message. The message is the error message. The v argument is the improper argument received by the procedure. The printed form of v is appended to message (using the error value conversion handler; see error-value->string-handler).

Additional arguments are concatenated to the error message like message and v. Every other additional argument (starting with the argument after v) must be a string, but a string need not have a following value argument.

(raise-arity-error name arity-v [arg-v ...])  any
  name : (or/c symbol? procedure?)
  arity-v : 
(or/c exact-nonnegative-integer?
      arity-at-least?
      (listof
       (or/c exact-nonnegative-integer?
             arity-at-least?)))
  arg-v : any/c = #f
Creates an exn:fail:contract:arity value and raises it as an exception. The name is used for the source procedure’s name in the error message.

The arity-v value must be a possible result from procedure-arity, except that it does not have to be normalized (see procedure-arity? for the details of normalized arities); raise-arity-error will normalize the arity and use the normalized form in the error message. If name is a procedure, its actual arity is ignored.

The arg-v arguments are the actual supplied arguments, which are shown in the error message (using the error value conversion handler; see error-value->string-handler); also, the number of supplied arg-vs is explicitly mentioned in the message.

(raise-syntax-error name    
  message    
  [expr    
  sub-expr    
  extra-sources])  any
  name : (or/c symbol? #f)
  message : string?
  expr : any/c = #f
  sub-expr : any/c = #f
  extra-sources : (listof syntax?) = null
Creates an exn:fail:syntax value and raises it as an exception. Macros use this procedure to report syntax errors.

The name argument is usually #f when expr is provided; it is described in more detail below. The message is used as the main body of the error message.

The optional expr argument is the erroneous source syntax object or S-expression (but the expression #f cannot be represented by itself; it must be wrapped as a syntax object). The optional sub-expr argument is a syntax object or S-expression (again, #f cannot represent itself) within expr that more precisely locates the error. Both may appear in the generated error-message text if error-print-source-location is #t. Source location information in the error-message text is similarly extracted from sub-expr or expr when at least one is a syntax object and error-print-source-location is #t.

If sub-expr is provided and not #f, it is used (in syntax form) for the exprs field of the generated exception record, else the expr is used if provided and not #f. In either case, the syntax object is consed onto extra-sources to produce the exprs field, or extra-sources is used directly for exprs if neither expr nor sub-expr is provided and not #f.

The form name used in the generated error message is determined through a combination of the name, expr, and sub-expr arguments:

9.2.2 Handling Exceptions

(call-with-exception-handler f thunk)  any
  f : (any/c . -> . any)
  thunk : (-> any)
Installs f as the exception handler for the dynamic extent of the call to thunk. If an exception is raised during the evaluation of thunk (in an extension of the current continuation that does not have its own exception handler), then f is applied to the raised value in the continuation of the raise call (but normally extended with a continuation barrier; see Prompts, Delimited Continuations, and Barriers and raise).

Any procedure that takes one argument can be an exception handler. If the exception handler returns a value when invoked by raise, then raise propagates the value to the “previous” exception handler (still in the dynamic extent of the call to raise, and under the same barrier, if any). The previous exception handler is the exception handler associated with the rest of the continuation after the point where the called exception handler was associated with the continuation; if no previous handler is available, the uncaught-exception handler is used (see below). In all cases, a call to an exception handler is parameterize-breaked to disable breaks, and it is wrapped with call-with-exception-handler to install the exception handler that reports both the original and newly raised exceptions.

A parameter that determines an exception handler used by raise when the relevant continuation has no exception handler installed with call-with-exception-handler or with-handlers. Unlike exception handlers installed with call-with-exception-handler, the handler for uncaught exceptions must not return a value when called by raise; if it returns, an exception is raised (to be handled by an exception handler that reports both the original and newly raised exception).

The default uncaught-exception handler prints an error message using the current error display handler (see error-display-handler) and then escapes by calling the current error escape handler (see error-escape-handler). The call to each handler is parameterized to set error-display-handler to the default error display handler, and it is parameterize-breaked to disable breaks. The call to the error escape handler is further parameterized to set error-escape-handler to the default error escape handler; if the error escape handler returns, then the default error escape handler is called.

When the current error display handler is the default handler, then the error-display call is parameterized to install an emergency error display handler that logs an error (see log-error) and never fails.

(with-handlers ([pred-expr handler-expr] ...)
  body ...+)
Evaluates each pred-expr and handler-expr in the order that they are specified, and then evaluates the bodys with a new exception handler during its dynamic extent.

The new exception handler processes an exception only if one of the pred-expr procedures returns a true value when applied to the exception, otherwise the exception handler is invoked from the continuation of the with-handlers expression (by raising the exception again). If an exception is handled by one of the handler-expr procedures, the result of the entire with-handlers expression is the return value of the handler.

When an exception is raised during the evaluation of bodys, each predicate procedure pred-expr is applied to the exception value; if a predicate returns a true value, the corresponding handler-expr procedure is invoked with the exception as an argument. The predicates are tried in the order that they are specified.

Before any predicate or handler procedure is invoked, the continuation of the entire with-handlers expression is restored, but also parameterize-breaked to disable breaks. Thus, breaks are disabled by default during the predicate and handler procedures (see Breaks), and the exception handler is the one from the continuation of the with-handlers expression.

The exn:fail? procedure is useful as a handler predicate to catch all error exceptions. Avoid using (lambda (x) #t) as a predicate, because the exn:break exception typically should not be caught (unless it will be re-raised to cooperatively break). Beware, also, of catching and discarding exceptions, because discarding an error message can make debugging unnecessarily difficult.

(with-handlers* ([pred-expr handler-expr] ...)
  body ...+)
Like with-handlers, but if a handler-expr procedure is called, breaks are not explicitly disabled, and the handler call is in tail position with respect to the with-handlers* form.

9.2.3 Configuring Default Handling

(error-escape-handler)  (-> any)
(error-escape-handler proc)  void?
  proc : (-> any)
A parameter for the error escape handler, which takes no arguments and escapes from the dynamic context of an exception. The default error escape handler escapes using (abort-current-continuation (default-continuation-prompt-tag) void).

The error escape handler is normally called directly by an exception handler, in a parameterization that sets the error display handler and error escape handler to the default handlers, and it is normally parameterize-breaked to disable breaks. To escape from a run-time error in a different context, use raise or error.

Due to a continuation barrier around exception-handling calls, an error escape handler cannot invoke a full continuation that was created prior to the exception, but it can abort to a prompt (see call-with-continuation-prompt) or invoke an escape continuation (see call-with-escape-continuation).

(error-display-handler)  (string? any/c . -> . any)
(error-display-handler proc)  void?
  proc : (string? any/c . -> . any)
A parameter for the error display handler, which is called by the default exception handler with an error message and the exception value. More generally, the handler’s first argument is a string to print as an error message, and the second is a value representing a raised exception.

The default error display handler displays its first argument to the current error port (determined by the current-error-port parameter) and extracts a stack trace (see continuation-mark-set->context) to display from the second argument if it is an exn value but not an exn:fail:user value.

The default error display handler in DrRacket also uses the second argument to highlight source locations.

To report a run-time error, use raise or procedures like error, instead of calling the error display handler directly.

(error-print-width)  (and/c exact-integer? (>=/c 3))
(error-print-width width)  void?
  width : (and/c exact-integer? (>=/c 3))
A parameter whose value is used as the maximum number of characters used to print a Racket value that is embedded in a primitive error message.

A parameter whose value is used by the default error display handler as the maximum number of lines of context (or “stack trace”) to print; a single “...” line is printed if more lines are available after the first cnt lines. A 0 value for cnt disables context printing entirely.

(error-value->string-handler)
  
(any/c exact-nonnegative-integer?
       . -> .
       string?)
(error-value->string-handler proc)  void?
  proc : 
(any/c exact-nonnegative-integer?
       . -> .
       string?)
A parameter that determines the error value conversion handler, which is used to print a Racket value that is embedded in a primitive error message.

The integer argument to the handler specifies the maximum number of characters that should be used to represent the value in the resulting string. The default error value conversion handler prints the value into a string (using the current global port print handler; see global-port-print-handler). If the printed form is too long, the printed form is truncated and the last three characters of the return string are set to “...”.

If the string returned by an error value conversion handler is longer than requested, the string is destructively “truncated” by setting the first extra position in the string to the null character. If a non-string is returned, then the string "..." is used. If a primitive error string needs to be generated before the handler has returned, the default error value conversion handler is used.

Calls to an error value conversion handler are parameterized to re-install the default error value conversion handler, and to enable printing of unreadable values (see print-unreadable).

A parameter that controls whether read and syntax error messages include source information, such as the source line and column or the expression. This parameter also controls the error message when a module-defined variable is accessed before its definition is executed; the parameter determines whether the message includes a module name. Only the message field of an exn:fail:read, exn:fail:syntax, or exn:fail:contract:variable structure is affected by the parameter. The default is #t.

9.2.4 Built-in Exception Types

(struct exn (message continuation-marks)
  #:extra-constructor-name make-exn
  #:transparent)
  message : string?
  continuation-marks : continuation-mark-set?
The base structure type for exceptions. The message field contains an error message, and the continuation-marks field contains the value produced by (current-continuation-marks) immediately before the exception was raised.

(struct exn:fail exn ()
  #:extra-constructor-name make-exn:fail
  #:transparent)
Raised for exceptions that represent errors, as opposed to exn:break.

(struct exn:fail:contract exn:fail ()
  #:extra-constructor-name make-exn:fail:contract
  #:transparent)
Raised for errors from the inappropriate run-time use of a function or syntactic form.

(struct exn:fail:contract:arity exn:fail:contract ()
  #:extra-constructor-name make-exn:fail:contract:arity
  #:transparent)
Raised when a procedure is applied to the wrong number of arguments.

Raised for division by exact zero.

Raised by functions like fx+ when the result would not be a fixnum.

(struct exn:fail:contract:continuation exn:fail:contract ()
  #:extra-constructor-name
  make-exn:fail:contract:continuation
  #:transparent)
Raised when a continuation is applied where the jump would cross a continuation barrier.

(struct exn:fail:contract:variable exn:fail:contract (id)
  #:extra-constructor-name make-exn:fail:contract:variable
  #:transparent)
  id : symbol?
Raised for a reference to a not-yet-defined top-level variable or module-level variable.

(struct exn:fail:syntax exn:fail (exprs)
  #:extra-constructor-name make-exn:fail:syntax
  #:transparent)
  exprs : (listof syntax?)
Raised for a syntax error that is not a read error. The exprs indicate the relevant source expressions, least-specific to most-specific.

(struct exn:fail:syntax:unbound exn:fail:syntax ()
  #:extra-constructor-name make-exn:fail:syntax:unbound
  #:transparent)
Raised by #%top or set! for an unbound identifier within a module.

(struct exn:fail:read exn:fail (srclocs)
  #:extra-constructor-name make-exn:fail:read
  #:transparent)
  srclocs : (listof srcloc?)
Raised for a read error. The srclocs indicate the relevant source expressions.

(struct exn:fail:read:eof exn:fail:read ()
  #:extra-constructor-name make-exn:fail:read:eof
  #:transparent)
Raised for a read error, specifically when the error is due to an unexpected end-of-file.

(struct exn:fail:read:non-char exn:fail:read ()
  #:extra-constructor-name make-exn:fail:read:non-char
  #:transparent)
Raised for a read error, specifically when the error is due to an unexpected non-character (i.e., “special”) element in the input stream.

(struct exn:fail:filesystem exn:fail ()
  #:extra-constructor-name make-exn:fail:filesystem
  #:transparent)
Raised for an error related to the filesystem (such as a file not found).

(struct exn:fail:filesystem:exists exn:fail:filesystem ()
  #:extra-constructor-name make-exn:fail:filesystem:exists
  #:transparent)
Raised for an error when attempting to create a file that exists already.

(struct exn:fail:filesystem:version exn:fail:filesystem ()
  #:extra-constructor-name make-exn:fail:filesystem:version
  #:transparent)
Raised for a version-mismatch error when loading an extension.

(struct exn:fail:network exn:fail ()
  #:extra-constructor-name make-exn:fail:network
  #:transparent)
Raised for TCP and UDP errors.

(struct exn:fail:out-of-memory exn:fail ()
  #:extra-constructor-name make-exn:fail:out-of-memory
  #:transparent)
Raised for an error due to insufficient memory, in cases where sufficient memory is at least available for raising the exception.

(struct exn:fail:unsupported exn:fail ()
  #:extra-constructor-name make-exn:fail:unsupported
  #:transparent)
Raised for an error due to an unsupported feature on the current platform or configuration.

(struct exn:fail:user exn:fail ()
  #:extra-constructor-name make-exn:fail:user
  #:transparent)
Raised for errors that are intended to be seen by end users. In particular, the default error printer does not show the program context when printing the error message.

(struct exn:break exn (continuation)
  #:extra-constructor-name make-exn:break
  #:transparent)
  continuation : continuation?
Raised asynchronously (when enabled) in response to a break request. The continuation field can be used by a handler to resume the interrupted computation.

A property that identifies structure types that provide a list of srcloc values. The property is normally attached to structure types used to represent exception information.

The property value must be a procedure that accepts a single value—the structure type instance from which to extract source locations—and returns a list of srclocs. Some error display handlers use only the first returned location.

As an example,
#lang racket
 
;; We create a structure that supports the
;; prop:exn:srcloc protocol.  It carries
;; with it the location of the syntax that
;; is guilty.
(define-struct (exn:fail:he-who-shall-not-be-named
                exn:fail)
  (a-srcloc)
  #:property prop:exn:srclocs
  (lambda (a-struct)
    (match a-struct
      [(struct exn:fail:he-who-shall-not-be-named
         (msg marks a-srcloc))
       (list a-srcloc)])))
 
;; We can play with this by creating a form that
;; looks at identifiers, and only flags specific ones.
(define-syntax (skeeterize stx)
  (syntax-case stx ()
    [(_ expr)
     (cond
       [(and (identifier? #'expr)
             (eq? (syntax-e #'expr) 'voldemort))
        (quasisyntax/loc stx
          (raise (make-exn:fail:he-who-shall-not-be-named
                  "oh dear don't say his name"
                  (current-continuation-marks)
                  (srcloc '#,(syntax-source #'expr)
                          '#,(syntax-line #'expr)
                          '#,(syntax-column #'expr)
                          '#,(syntax-position #'expr)
                          '#,(syntax-span #'expr)))))]
       [else
        ;; Otherwise, leave the expression alone.
        #'expr])]))
 
(define (f x)
  (* (skeeterize x) x))
 
(define (g voldemort)
  (* (skeeterize voldemort) voldemort))
 
;; Examples:
(f 7)
(g 7)
;; The error should highlight the use
;; of the one-who-shall-not-be-named
;; in g.

(exn:srclocs? v)  boolean?
  v : any/c
Returns #t if v has the prop:exn:srclocs property, #f otherwise.

Returns the srcloc-getting procedure associated with v.

(struct srcloc (source line column position span)
  #:extra-constructor-name make-srcloc
  #:transparent)
  source : any/c
  line : (or/c exact-positive-integer? #f)
  column : (or/c exact-nonnegative-integer? #f)
  position : (or/c exact-positive-integer? #f)
  span : (or/c exact-nonnegative-integer? #f)
The fields of a srcloc instance are as follows: