RaiseError

If you develop a new application, you should use the THROW statement instead.

SQL Server RAISEERROR statement overview

The RAISERROR statement allows you to generate your own error messages and return these messages back to the application using the same format as a system error or warning message generated by SQL Server Database Engine. In addition, the RAISERROR statement allows you to set a specific message id, level of severity, and state for the error messages.

The following illustrates the syntax of the RAISERROR statement:

1234	RAISERROR ( { message_id | message_text | @local_variable }      { ,severity ,state }      [ ,argument [ ,…n ] ] )      [ WITH option [ ,…n ] ];

Let’s examine the syntax of the RAISERROR for better understanding.

message_id

The message_id is a user-defined error message number stored in the sys.messages catalog view.

To add a new user-defined error message number, you use the stored procedure sp_addmessage. A user-defined error message number should be greater than 50,000. By default, the RAISERROR statement uses the message_id 50,000 for raising an error.

The following statement adds a custom error message to the sys.messages view:

1234	EXEC sp_addmessage     @msgnum = 50005,     @severity = 1,     @msgtext = ‘A custom error message’;

To verify the insert, you use the following query:

123456

SELECT        *FROM        sys.messagesWHERE     message_id = 50005;

To use this message_id, you execute the RAISEERROR statement as follows:

1	RAISERROR ( 50005,1,1)

Here is the output:

12	A custom error messageMsg 50005, Level 1, State 1

To remove a message from the sys.messages, you use the stored procedure sp_dropmessage. For example, the following statement deletes the message id 50005:

12	EXEC sp_dropmessage     @msgnum = 50005;

message_text

The message_text is a user-defined message with formatting like the printf function in C standard library. The message_text can be up to 2,047 characters, 3 last characters are reserved for ellipsis (…). If the message_text contains 2048 or more, it will be truncated and is padded with an ellipsis.

When you specify the message_text, the RAISERROR statement uses message_id 50000 to raise the error message.

The following example uses the RAISERROR statement to raise an error with a message text:

1	RAISERROR ( ‘Whoops, an error occurred.’,1,1)

The output will look like this:

12	Whoops, an error occurred.Msg 50000, Level 1, State 1

severity

The severity level is an integer between 0 and 25, with each level representing the seriousness of the error.

123	0–10 Informational messages11–18 Errors19–25 Fatal errors

state

The state is an integer from 0 through 255. If you raise the same user-defined error at multiple locations, you can use a unique state number for each location to make it easier to find which section of the code is causing the errors. For most implementations, you can use 1.

WITH option

The option can be LOG, NOWAIT, or SETERROR:

• WITH LOG logs the error in the error log and application log for the instance of the SQL Server Database Engine.
• WITH NOWAIT sends the error message to the client immediately.
• WITH SETERROR sets the ERROR_NUMBER and @@ERROR values to message_id or 50000, regardless of the severity level.

SQL Server RAISERROR examples

Let’s take some examples of using the RAISERROR statement to get a better understanding.

A) Using SQL Server RAISERROR with TRY CATCH block example

In this example, we use the RAISERROR inside a TRY block to cause execution to jump to the associated CATCH block. Inside the CATCH block, we use the RAISERROR to return the error information that invoked the CATCH block.

1234567891011121314151617

DECLARE     @ErrorMessage  NVARCHAR(4000),     @ErrorSeverity INT,     @ErrorState    INT; BEGIN TRY    RAISERROR(‘Error occurred in the TRY block.’, 17, 1);END TRYBEGIN CATCH    SELECT         @ErrorMessage = ERROR_MESSAGE(),         @ErrorSeverity = ERROR_SEVERITY(),         @ErrorState = ERROR_STATE();     — return the error inside the CATCH block    RAISERROR(@ErrorMessage, @ErrorSeverity, @ErrorState);END CATCH;

Here is the output:

12	Msg 50000, Level 17, State 1, Line 16Error occurred in the TRY block.

B) Using SQL Server RAISERROR statement with a dynamic message text example

The following example shows how to use a local variable to provide the message text for a RAISERROR statement:

123456789

DECLARE @MessageText NVARCHAR(100);SET @MessageText = N’Cannot delete the sales order %s’; RAISERROR(    @MessageText, — Message text    16, — severity    1, — state    N’2001′ — first argument to the message text);

The output is as follows:

12	Msg 50000, Level 16, State 1, Line 5Cannot delete the sales order 2001

When to use RAISERROR statement

You use the RAISERROR statement in the following scenarios:

• Troubleshoot Transact-SQL code.
• Return messages that contain variable text.
• Examine the values of data.
• Cause the execution to jump from a TRY block to the associated CATCH block.
• Return error information from the CATCH block to the callers, either calling batch or application.