8.5 Error and Exception Handling

The built-in predicates described in this section are used to alter the control flow to meet exception and error conditions. The equivalent of a raise_exception/1 is also executed by the built-in predicates when errors occur.

catch(:ProtectedGoal,?Pattern,:Handler) ISO

on_exception(?Pattern,:ProtectedGoal,:Handler)

throw(+Exception) ISO

raise_exception(+Exception)

catch/3 is the same as on_exception/3 (but note different argument order), and throw/1 is the same as raise_exception/1. on_exception/3 calls ProtectedGoal. If this succeeds or fails, so does the call to on_exception/3. If however, during the execution of ProtectedGoal, there is a call to raise_exception(Exception), then Exception is copied and the stack is unwound back to the call to on_exception/3, whereupon the copy of Exception is unified with Pattern. If this unification succeeds, then on_exception/3 calls the goal Handler in order to determine the success or failure of on_exception/3. Otherwise, the stack keeps unwinding, looking for an earlier invocation of on_exception/3. Exception may be any term.

In a development system, any previously uncaught exception is caught and an appropriate error message is printed before returning to the top level. In recursive calls to Prolog from C, uncaught exceptions are returned back to C instead. The printing of these and other messages in a development system is handled by the predicate print_message/2 (see Messages and Queries).

The format of the exception raised by the built-in predicates depends on the execution mode. In iso execution mode the format is

     error(ISO_Error, SICStus_Error)

where ISO_Error is the error term prescribed by the ISO Prolog standard, while SICStus_Error is the part defined by the standard to be implementation dependent. In case of SICStus Prolog this is the SICStus error term, which normally contains additional information, such as the goal and the argument number causing the error. Arguments are numbered from 1 upwards.

In sicstus execution mode, the SICStus error term is used when raising an exception in a built-in predicate.

The list below itemizes the error terms, showing the ISO_Error and SICStus_Error form of each one, in that order. Note that the SICStus and ISO error terms do not always belong to the same error class, and that the context and consistency error classes are extensions to the ISO Prolog standard.

The goal part of the error term may optionally have the form $@(Callable,PC) where PC is an internal encoding of the line of code containing the culprit goal or one of its ancestors.

instantiation_error

instantiation_error(Goal,ArgNo)

Goal was called with insufficiently instantiated variables.

type_error(TypeName,Culprit)

type_error(Goal,ArgNo,TypeName,Culprit)

Goal was called with the wrong type of argument(s). TypeName is the expected type and Culprit what was actually found.

domain_error(Domain,Culprit)

domain_error(Goal,ArgNo,Domain,Culprit)

Goal was called with argument(s) of the right type but with illegal value(s). Domain is the expected domain and Culprit what was actually found.

existence_error(ObjectType,Culprit)

existence_error(Goal,ArgNo,ObjectType,Culprit,Reserved)

Something does not exist as indicated by the arguments. If the unknown Prolog flag is set to error, this error is raised with ArgNo set to 0 when an undefined predicate is called.

permission_error(Operation,ObjectType,Culprit)

permission_error(Goal,Operation,ObjectType,Culprit,Reserved)

The Operation is not permitted on Culprit of the ObjectType.

context_error(ContextType,CommandType)

context_error(Goal,ContextType,CommandType)

The CommandType is not permitted in ContextType.

syntax_error(Message)

syntax_error(Goal,Position,Message,Tokens,AfterError)

A syntax error was found when reading a term with read/[1,2] or assembling a number from its characters with number_chars/2. In the former case this error is raised only if the syntax_errors flag is set to error.

evaluation_error(ErrorType,Culprit)

evaluation_error(Goal,ArgNo,ErrorType,Culprit)

An incorrect arithmetic expression was evaluated. Only occurs in iso execution mode.

representation_error(ErrorType)

representation_error(Goal,ArgNo,ErrorType)

A representation error occurs when the program tries to compute some well-defined value that cannot be represented, such as a compound term with arity > 255.

consistency_error(Culprit1,Culprit2,Message)

consistency_error(Goal,Culprit1,Culprit2,Message)

A consistency error occurs when two otherwise valid values or operations have been specified that are inconsistent with each other.

resource_error(ResourceType)

resource_error(Goal,ResourceType)

A resource error occurs when SICStus Prolog has insufficient resources to complete execution. The only value for ResourceType that is currently in use is memory.

system_error

system_error(Message)

An error occurred while dealing with the operating system.

It is possible to handle a particular kind of existence errors locally: calls to undefined predicates. This can be done by defining clauses for:

unknown_predicate_handler(+Goal,+Module,-NewGoal) hook

user:unknown_predicate_handler(+Goal,+Module,-NewGoal)

Called as a result of a call to an undefined predicate. Goal is bound to the goal of the undefined predicate and Module to the module where the call was made. If this predicate succeeds, Module:NewGoal is called; otherwise, the action taken is governed by the unknown Prolog flag.

The following example shows an auto-loader for library packages:

     user:unknown_predicate_handler(Goal, Module, Goal) :-
             functor(Goal, Name, Arity),
             require(Module:(Name/Arity)).