Error_Handler Rule

Official Content
This documentation is valid for:
Provides a dynamic way to perform user-specific actions when a database-related error occurs during program runtime. Transactional and connection errors are detected and a user-defined routine is executed.



Is the name of a subroutine contained in the program which makes use of this rule.


The error_handler rule is declarative. It applies to the whole program, anywhere that an active error_handler command does not exist.

The scope of the rule or command will only be taken into consideration by the program that makes use of it. This means that it will not affect any programs called by the program that uses it, and if a program that uses this rule/command happens to call another program which also makes use of it, the second program will ignore the specification of the rule/command belonging to the calling program (the original program) and will not affect the calling program at all. Again, it should be pointed out that the use of this rule/command is limited to the program that uses it.

The error_handler program is called whenever a database related error is detected at run time. It receives no parameters and it allows usage of the &err global variable to identify GeneXus Error as specified below:


Data Type




It contains the GeneXus standard error codes or 999 if an undefined database error code is detected. We strongly recommend using this variable whenever possible to identify errors. This technique will make your programs portable from one GeneXus platform to another. The following list shows &Err values and their meaning:

1                       Duplicate record
101                   End of file
103                   Object locked (record or file)
105                   Object not found
106                   Database already exists
500                   Parent primary key not found
600                   Referential Integrity error raised (only Java Generator)
999                   Unexpected DBMS error.

Also, it is possible to receive more detailed information about database native error codes and descriptions, defining these variables


Data Type




It contains the native DBMS error code. Its value is set only when &Err is greater than 500, otherwise, its value is undefined.



It contains the native SQLSate error code.



It contains the native DBMS error message. Its value is set only when &Err is greater than 500, otherwise, its value is undefined.



It contains a descriptive identification of the operation that had been taking place when the error was encountered. Possible values for this variable are: Declare, Fetch, Insert, Update, Delete



It contains the name of the table (if any) that was being accessed when the error occurred. This variable may contain the special value 'N/A' if no table is related to the database operation (i.e. database creation, remote procedure calls, etc.).



Used as a return code by the error_handler. Depending on the value set by the error_handler, the program will:

0 = Continue processing - The error is ignored.
1 = Retry the operation (retries the specified amount using the Lock retry count property). If the error continues after the retries it continues with the processing 
2 = Cancel application execution (at any SQL error it will cancel the application)
3 = Perform default GeneXus processing 
(Default value) (it will behave in the same way as a program without error handler (some error are ignored like locked, duplicate, etc , and the rest cancel the application execution))


  • If the &gxErrOpt is set to 0 or 1 it will not show the error in the standard output because it's being captured by the GeneXus generated code.
  • These Variables are not global and can be used on each object that has an Error_handler rule or command.
  • Any DBMS exception is caught by the error_hanlder rule or command. The standard variables are loaded then in the following cases:
    • &gxDBErr and &gxDBTxt are loaded in any case
    • &gxDBSqlState is loaded in:
      • Java
        • All DBMSes
      • .Net
        • PostgreSQL
        • Informix   
      • .Net Core:
        • MySQL
        • PostgreSQL





Sub 'DBErrors'
    If &Err = 1
        Msg('Duplicate record')


Objects: ProceduresTransactions, Web Panels
Languages: .Net, Java, .Net Core

See Also

Error_Handler Command