error

R2026b

Throw error and display message

collapse all in page

Syntax

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

Description

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

example

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 the corresponding scalar value in 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.

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.

example

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
Not enough input arguments.

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

Input Arguments

collapse all

Information about the error, specified as a text scalar containing format specification. 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. The % character is treated as a format specifier. Use %% to represent a percent character in msg. For more information, see Formatting Text.

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 text scalar containing component and mnemonic fields. 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'

One or more values that replace the conversion specifiers in msg, each value is 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 the fields in this table. The error function ignores any additional fields in errorStruct.

FieldnameDescription
message

Error message, specified as a text scalar. The error function displays the message as specified and does not convert special characters.

If you do not specify a value for this field, the error message defaults to ''.

identifier

Error identifier, specified as a text scalar. For more information about error identifiers, see MException.

If you do not specify a value for this field, the error identifier defaults to ''.

stack

Stack trace information for the error, specified as a structure array with the following fields. The structure array has the same format as the structure returned by dbstack("-completenames"). The error function ignores any additional fields in stack.

  • file — Absolute path of the file in which the function appears.

  • name — Name of the function within the file.

  • line — Line number of the function call. If you specify a noninteger value, error uses only the real, integer part. The error function also replaces invalid line values, such as NaN or Inf, with 0.

If you do not specify a value for the stack field, the stack trace information for the error defaults to a 0-by-1 structure with the fields file, name, and line.

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

expand all

Version History

Introduced before R2006a

expand all

See Also

| | | | | | |

Topics