MATLAB Function Reference

error - Display message and abort function

Syntax

error('message') error('message', a1, a2, ...) error('message_id', 'message') error('message_id', 'message', a1, a2, ...) error(message_struct)

Description

error('message') displays an error message and returns control to the keyboard. The error message contains the input string message.

The error command has no effect if message is an empty string.

error('message', a1, a2, ...) displays a message string that contains formatting conversion characters, such as those used with the MATLAB^® sprintf function. Each conversion character in message is converted to one of the values a1, a2, ... in the argument list.

Note MATLAB converts special characters (like \n and %d) in the error message string only when you specify more than one input argument with error. See Example 3 below.

error('message_id', 'message') attaches a unique message identifier, or message_id, to the error message. The identifier enables you to better identify the source of an error. See Message Identifiers in the MATLAB documentation for more information on the message_id argument and how to use it.

error('message_id', 'message', a1, a2, ...) includes formatting conversion characters in message, and the character translations a1, a2, ....

error(message_struct) accepts a scalar error structure input message_struct with at least one of the fields message, identifier, and stack. (See the help for lasterror for more information on these fields.) When the message_struct input includes a stack field, the stack field of the error will be set according to the contents of the stack input. When specifying a stack input, use the absolute file name and the entire sequence of functions that nests the function in the stack frame. (This is the same as the string returned by dbstack('-completenames')). If message_struct is an empty structure, no action is taken and error returns without exiting from the M-file.

Remarks

In addition to the message_id and message, the error function also determines where the error occurred, and provides this information using the stack field of the structure returned by lasterror. The stack field contains a structure array in the same format as the output of dbstack('-completenames'). This stack points to the line, function, and M-file in which the error occurred.

Examples

Example 1

The error function provides an error return from M-files:

function foo(x,y)
if nargin ~= 2
     error('Wrong number of input arguments')
end

The returned error message looks like this:

foo(pi)

??? Error using ==> foo
Wrong number of input arguments

Example 2

Specify a message identifier and error message string with error:

error('MyToolbox:angleTooLarge', ... 
      'The angle specified must be less than 90 degrees.');

In your error handling code, use lasterror to determine the message identifier and error message string for the failing operation:

err = lasterror;

err.message
ans =
   The angle specified must be less than 90 degrees.

err.identifier
ans =
   MyToolbox:angleTooLarge

If this error is thrown from code in an M-file, you can find the M-file name, function, and line number using the stack field of the structure returned by lasterror:

err.stack
ans = 
    file: 'd:\mytools\plotshape.m'
    name: 'check_angles'
    line: 26

Example 3

MATLAB converts special characters (like \n and %d) in the error message string only when you specify more than one input argument with error. In the single-argument case shown below, \n is taken to mean backslash-n. It is not converted to a newline character:

error('In this case, the newline \n is not converted.')
??? In this case, the newline \n is not converted.

But, when more than one argument is specified, MATLAB does convert special characters. This holds true regardless of whether the additional argument supplies conversion values or is a message identifier:

error('ErrorTests:convertTest', ... 
      'In this case, the newline \n is converted.')
??? In this case, the newline 
 is converted.