MATLAB^®

error - Display message and abort function

Syntax

error('msgID', 'errmsg', v1, v2 ...) error('errmsg', v1, v2, ...) error('errmsg') error(msgStruct)

Description

error('msgID', 'errmsg', v1, v2 ...) displays a descriptive message errmsg when the currently-running M-file program encounters an error condition. Depending on how the program code responds to the error, MATLAB either enters a catch block to handle the error condition, or exits the program.

The msgID argument is a unique message identifier string that MATLAB attaches to the error message when it throws the error. A message identifier has the format component:mnemonic. Its purpose is to better identify the source of the error (see Message Identifiers in the MATLAB Programming Fundamentals documentation for more information).

The errmsg argument is a character string that informs the user about the cause of the error and can also suggest how to correct the faulty condition. The errmsg string can include predefined escape sequences, such as \n for newline, and conversion specifiers, such as %d for a decimal number.

The v1, v2, ... arguments represent values or substrings that are to replace conversion specifiers used in the errmsg string. The format is the same as that used with the sprintf function. For example, if errmsg is "Error on line %d, command %s", then v1 is the line number at which the error was detected, and v2 is the command that failed. The vN arguments replace the conversion specifiers at the time of execution.

Valid escape sequences for the errmsg string are \b, \f, \n, \r, \t, and \x or \ when followed by a valid hexadecimal or octal number, respectively. Following a backslash in the errmsg with any other character causes MATLAB to issue a warning. Conversion specifiers are similar to those used in the C programming language and in the sprintf function.

All string input arguments must be enclosed in single quotation marks. If errMsg is an empty string, the error command has no effect.

error('errmsg', v1, v2, ...)reports an error without including a message identifier in the error report. Although including a message identifier in an error report is recommended, it is not required.

error('errmsg') is the same as the above syntax, except that the errmsg string contains no conversion specifiers, no escape sequences, and no substitution value (v1, v2, ...) arguments. All characters in errmsg are interpreted exactly as they appear in the errmsg argument. MATLAB displays the \t in 'C:\testdir' for example, as a backslash character followed by the letter t, and not as a horizontal tab.

error(msgStruct) accepts a scalar error structure input msgStruct with at least one of the fields message, identifier, and stack. (See the help for lasterror for more information on these fields.) When the msgStruct 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 msgStruct is an empty structure, no action is taken and error returns without exiting from the M-file.

Remarks

The error function also determines where the error occurred and provides this information in the stack field of the structure returned by MException.last. This field contains a structure array that has the same format as the output of the dbstack function. This stack points to the line where the error function was called.

Examples

Example 1 — Simple Error Message, lasterror

Write a short M-file errtest1 that throws an error when called with an incorrect number of input arguments. Include a message identifier 'myApp:argChk' and error message:

function errtest1(x, y)
if nargin ~= 2
    error('myApp:argChk', Wrong number of input arguments')
end

Call the function with an incorrect number of inputs. The call to nargin, a function that checks the number of inputs, fails and the program calls error:

errtest1(pi)
	
??? Error using ==> errtest1 at 3
Wrong number of input arguments

You can use lasterror to get information on the last error thrown:

err = lasterror
err = 
       message: [1x120 char]
    identifier: 'myApp:argChk'
         stack: [1x1 struct]

err.stack
ans = 
    file: 'c:\work\errtest1.m'
    name: 'errtest1'
    line: 3

Example 2 — Formatted Message String, lasterror

Specify a message identifier and formatted error message string with error:

function plotshape(newAngle)
maxAngle = 90;
    check_angles(newAngle, maxAngle)

function check_angles(newAngle, maxAngle)
if newAngle > maxAngle 
  error('MyToolbox:angleTooLarge', ...
    'Specified angle must be less than %d degrees.', ...
     maxAngle)
end

Run the function, which then displays the error message:

plotshape(100)
??? Error using ==> plotshape>check_angles at 14
The angle specified must be less than 90 degrees.

Error in ==> plotshape at 4
    check_angles(newAngle, maxAngle)

Use the lasterror function to obtain more information about the error:

err = lasterror
err = 
       message: [1x157 char]
    identifier: 'MyToolbox:angleTooLarge'
         stack: [2x1 struct]

Show the message string and identifier:

err.message
ans =
   Error using ==> plotshape>check_angles at 14
   The angle specified must be less than 90 degrees.

err.identifier
ans =
   MyToolbox:angleTooLarge

Show the most recent entry on the stack:

stk = err.stack(1)
stk = 
    file: 'd:\mytools\plotshape.m'
    name: 'check_angles'
    line: 14

Example 3 — Special Characters

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.