error

Throw error and display message

collapse all in page

Syntax

error(msg)
error(msg,A1,...,An)
error(errID,___)
error(errorStruct)
error(correction,___)

Description

example

error(msg) throws an error and displays an error message.

error(msg,A1,...,An) displays an error message that contains formatting conversion characters, such as those used with the MATLAB® sprintf function. Each conversion character in msg is converted to one of the values A1,...,An.

error(errID,___) includes an error identifier on the exception. The identifier enables you to distinguish errors and to control what happens when MATLAB encounters the errors. You can include any of the input arguments in the previous syntaxes.

example

error(errorStruct) throws an error using the fields in a scalar structure.

example

error(correction,___) provides a suggested fix for the exception. You can include any of the input arguments in the previous syntaxes.

Examples

collapse all

msg = 'Error occurred.';
error(msg)
Error occurred.

Throw a formatted error message with a line break. You must specify more than one input argument with error if you want MATLAB to convert special characters (such as \n) in the error message. Include information about the class of variable n in the error message.

n = 7;
if ~ischar(n)
   error('Error. \nInput must be a char, not a %s.',class(n))
end
Error.
Input must be a char, not a double.

If you only use one input argument with error, then MATLAB does not convert \n to a line break.

if ~ischar(n)
   error('Error. \nInput must be a char.')
end
Error. \nInput must be a char.

Throw an error with an identifier.

if ~ischar(n)
   error('MyComponent:incorrectType',...
       'Error. \nInput must be a char, not a %s.',class(n))
end
Error.
Input must be a char, not a double.

Use the MException.last to view the last uncaught exception.

exception = MException.last
exception = 

  MException with properties:

    identifier: 'MyComponent:incorrectType'
       message: 'Error. 
Input must be a char, not a double.'
         cause: {0x1 cell}
         stack: [0x1 struct]

Create structure with message and identifier fields. To keep the example simple, do not use the stack field.

errorStruct.message = 'Data file not found.';
errorStruct.identifier = 'MyFunction:fileNotFound';
errorStruct = 

       message: 'Data file not found.'
    identifier: 'MyFunction:fileNotFound'

Throw the error.

error(errorStruct)
Data file not found.

Create a function hello that requires one input argument. Add a suggested input argument "world" to the error message.

function hello(audience)
if nargin < 1
    aac = matlab.lang.correction.AppendArgumentsCorrection('"world"');
    error(aac, 'MATLAB:notEnoughInputs', 'Not enough input arguments.')   
end
fprintf("Hello, %s!\n", audience)
end

Call the function without an argument.

hello
Error using hello (line 4)
Not enough input arguments.

Did you mean:
>> hello("world")

Input Arguments

collapse all

Information about the error, specified as a character vector or string scalar. This message displays as the error message. To format the message, use escape sequences, such as \t or \n. You also can use any format specifiers supported by the sprintf function, such as %s or %d. Specify values for the conversion specifiers via the A1,...,An input arguments. For more information, see Formatting Text.

Note

You must specify more than one input argument with error if you want MATLAB to convert special characters (such as \t, \n, %s, and %d) in the error message.

Example: 'File not found.'

Identifier for the error, specified as a character vector or string scalar. Use the error identifier to help identify the source of the error or to control a selected subset of the errors in your program.

The error identifier includes one or more component fields and a mnemonic field. Fields must be separated with colon. For example, an error identifier with a component field component and a mnemonic field mnemonic is specified as 'component:mnemonic'. The component and mnemonic fields must each begin with a letter. The remaining characters can be alphanumerics (A–Z, a–z, 0–9) and underscores. No white-space characters can appear anywhere in errID. For more information, see MException.

Example: 'MATLAB:singularMatrix'

Example: 'MATLAB:narginchk:notEnoughInputs'

Values that replace the conversion specifiers in msg, specified as a character vector, string scalar, or numeric scalar.

Error reporting information, specified as a scalar structure. The structure must contain at least one of these fields.

message

Error message. For more information, see msg.

identifier

Error identifier. For more information, see errID.

stack

Stack field for the error. When errorStruct includes a stack field, error uses it to set the stack field of the error. When you specify stack, use the absolute file name and the entire sequence of functions that nests the function in the stack frame. This character vector is the same as the one returned by dbstack('-completenames').

Suggested fix for this exception, specified as a matlab.lang.correction.AppendArgumentsCorrection, matlab.lang.correction.ConvertToFunctionNotationCorrection, or matlab.lang.correction.ReplaceIdentifierCorrection object.

Tips

  • When you throw an error, MATLAB captures information about it and stores it in a data structure that is an object of the MException class. You can access information in the exception object by using try/catch. Or, if your program terminates because of an exception and returns control to the Command Prompt, you can use MException.last.

  • MATLAB does not cease execution of a program if an error occurs within a try block. In this case, MATLAB passes control to the catch block.

  • If all inputs to error are empty, MATLAB does not throw an error.

Extended Capabilities

See Also

| | | | | |

Topics

Introduced before R2006a

MATLAB Documentation

Support