4.15.4 Error Classes

Exceptions thrown by the Prolog system are called errors.

Error terms have the form:

error(ISO_Error, SICStus_Error)

where the principal functor of ISO_Error (resp. SICStus_Error) indicates the error class (see ref-ere-err). The classification always coincides.

Please note: Don’t throw error terms except when you re-throw a previously caught error term. They correspond to the exceptions thrown by the built-in predicates. Throwing such forged error terms can lead to unexpected results.

See lib-types for an alternative interface to throwing error exceptions, which tries to include line number information for source-linked debugging.

Error messages like the one shown earlier are printed using the built-in predicate print_message/2. One of the arguments to print_message/2 is the exception term. print_message/2 can be customized, as described in ref-msg.

The set of error classes used by the system has been kept small:

Instantiation Error   ISO

An input argument is insufficiently instantiated.

Uninstantiation Error   ISO

An input argument is too instantiated.

Type Error   ISO

An input argument is of the wrong type.

Domain Error   ISO

An input argument is illegal but of the right type.

Evaluation Error   ISO

An incorrect arithmetic expression was evaluated.

Representation Error   ISO

A computed value cannot be represented.

Existence Error   ISO

Something does not exist.

Permission Error   ISO

Specified operation is not permitted.

Context Error

Specified operation is not permitted in this context.

Consistency Error

Two otherwise correct values are inconsistent with each other.

Syntax Error   ISO

Error in reading a term.

Resource Error   ISO

Some resource limit has been exceeded.

System Error   ISO

An error detected by the operating system.

The format of the exception thrown by the built-in predicates 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 defined. This so called SICStus error term has the same principal functor as ISO_Error but more arguments containing additional information, such as the goal and the argument number causing the error. Arguments are numbered from 1 upwards. An argument number given as zero means that an unspecific argument caused the error.

The list below itemizes the error terms, showing the ISO_Error and SICStus_Error form of each one, in that order. The SICStus and ISO error terms always belong to the same error class, but note 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. To decompose an annotated goal AGoal into a Goal proper and a SourceInfo descriptor term, indicating the source position of the goal, use:

?- goal_source_info(AGoal, Goal, SourceInfo).

The reference page gives details about the SourceInfo format. See mpg-ref-goal_source_info.

instantiation_error   ISO

instantiation_error(Goal,ArgNo)

Goal was called with insufficiently instantiated arguments.

uninstantiation_error(Culprit)   ISO

uninstantiation_error(Goal,ArgNo,Culprit)

Goal was called with too instantiated arguments, expecting Culprit to be uninstantiated.

type_error(TypeName,Culprit)   ISO

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)   ISO

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)   ISO

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

Something does not exist as indicated by the arguments. See ref-ere-err-exi for ways of controlling this behavior.

permission_error(Operation,ObjectType,Culprit)   ISO

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

The Operation is not permitted on Culprit of the ObjectType. See ref-ere-err-per for ways of controlling this behavior.

context_error(ContextType,CommandType)

context_error(Goal,ContextType,CommandType)

The CommandType is not permitted in ContextType.

syntax_error(Message)   ISO

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 or number_codes/2. See ref-ere-err-syn for ways of controlling this behavior.

evaluation_error(ErrorType,Culprit)   ISO

evaluation_error(Goal,ArgNo,ErrorType,Culprit)

An incorrect arithmetic expression was evaluated.

representation_error(ErrorType)   ISO

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)   ISO

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   ISO

system_error(Message)

An error occurred while dealing with the operating system.

Most exception terms include a copy of the Goal that threw the exception.

In general, built-in predicates that cause side-effects, such as the opening of a stream or asserting a clause into the Prolog database, attempt to do all error checking before the side-effect is performed. Unless otherwise indicated in the documentation for a particular predicate or error class, it should be assumed that goals that throw exceptions have not performed any side-effect.