Documentation Center

  • Trial Software
  • Product Updates

error

Display message and abort function

Syntax

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

Description

error('msgIdent', 'msgString', v1, v2, ..., vN) generates an exception if the currently-running function tests 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 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 escape sequences such as \t or \n, as well as any of the format specifiers supported by the sprintf function (such as %s or %d). Additional arguments v1, v2, ..., vN provide values that correspond to and replace the conversion specifiers.

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. See Formatting Strings for more detailed information on using string formatting commands.

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:\testFolder' 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 the function.

Examples

Example 1 — Simple Error Message

Write a short function 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 (line 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.

More About

expand all

Tips

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 Capture Information About Exceptions 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 try, 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:

FunctionDescription
errorThrow exception with specified error message.
assertEvaluate given expression and throw exception if false.
throwThrow exception based on specified MException object.
throwAsCallerThrow exception that appears to have been thrown by the calling function.
rethrowReissue previously caught exception.

See Also

| | | | | | | | | | | |

Was this topic helpful?