Learn more about MATLAB

error - Display message and abort function

Syntax

error('msgIdent', 'msgString', v1, v2, ...) error('msgString', v1, v2, ...) error('msgString') error(msgStruct)

Description

error('msgIdent', 'msgString', v1, v2, ...) generates an exception if the currently-running M-file program test for and confirms a faulty or unexpected condition. Depending on how the program has been designed to respond to the error, MATLAB either enters a catch block to handle the error condition, or exits the program.

The msgIdent 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 msgString 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 msgString 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 msgString string. The format is the same as that used with the sprintf function. For example, if msgString 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 msgString 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 msgString 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 msgString is an empty string, the error command has no effect.

error('msgString', 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('msgString') is the same as the above syntax, except that the msgString string contains no conversion specifiers, no escape sequences, and no substitution value (v1, v2, ...) arguments. All characters in msgString are interpreted exactly as they appear in the msgString 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. 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 captures what information it can about the error that occurred and stores it in a data structure that is an object of the MException class. This error record contains the error message string, message identifier, the error stack, and optionally an array of other exception objects that are intended to provide information as to the cause of the exception. See Capturing Information About the Error for more information on how to access and use an exception object.

You can access information in the exception object using the catch function as documented in the catch reference page. If your program terminates because of an exception and returns control to the Command Prompt, you can access the exception object using the MException.last command.

The error function also determines where the error occurred and provides this information in the stack field of the MException object. 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.

The following table shows the MATLAB functions that can be useful for throwing an exception:

Function	Description
`error`	Throw exception with specified error message.
`assert`	Evaluate given expression and throw exception if false.
`throw`	Throw exception based on specified MException object.
`throwAsCaller`	Throw exception that appears to have been thrown by the calling function.
`rethrow`	Reissue previously caught exception.

Examples

Example 1 — Simple Error Message

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

If you run this function from the Command Window, you can use the MException.last method to view the exception object:

err = MException.last
err = 
  MException

  Properties:
    identifier: 'myApp:argChk'
       message: 'Wrong number of input arguments'
         cause: {}
         stack: [1x1 struct]
  Methods

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

Example 2 — 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.