exception = MException(msgIdent, msgString, v₁, v₂, ..., v_N) captures information about a specific error and stores it in MException object, exception. Information stored in the object includes a message identifier msgIdent and an error message string msgString. Optional arguments v₁, v₂, ... represent text or numeric values that replace conversion specifiers in msgString at run time.

Message identifier msgIdent is a character string composed of at least two substrings, the component and the mnemonic, separated by a colon (e.g., component:mnemonic). The purpose of the identifier is to better identify the source of the error. See the documentation on Message Identifiers for more information.

Message string msgString 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 v₁, v₂, ..., v_N provide values that correspond to and replace the conversion specifiers.

For example, if msgString is "Error on line %d, command %s", then v₁ is the line number at which the error was detected, and v₂ is the command that failed. See Formatting Strings in the MATLAB Programming Fundamentals documentation for more detailed information on using string formatting commands.

The exception output is an object of the MException class. MException is the constructor for this class. In addition to calling the constructor directly, you can also create an object of MException with any of the following functions: error and assert. See the documentation and figure in the section The MException Class for more information on this class.

Properties

The MException object has four properties: identifier, message, stack, and cause. Click any of the links below to find out more about MException properties:

Property	Description
`identifier`	Identifies the error.
`message`	Formatted error message that is displayed.
`stack`	Structure containing stack trace information such as file name, function name, and line number where the `MException` was thrown.
`cause`	Cell array of `MException` that caused this exception to be created.

Methods

The MException class has the following methods. Click any of the links below to find out more about MException methods:

Method	Description
`addCause`	Appends an `MException` to the `cause` field of another `MException`.
`eq`	Tests scalar `MException` objects for equality.
`getReport`	Returns a formatted message string that uses the same format as errors thrown by internal MATLAB code.
`isequal`	Tests scalar `MException` objects for equality.
`last`	Returns an `MException` object for the most recently thrown exception.
`ne`	Tests scalar `MException` objects for inequality.
`rethrow`	Reissues an exception that has been caught, causing the program to stop.
`throw`	Issues an exception from the currently running function.
`throwAsCaller`	Issues an exception from the currently running function, also omitting the current stack frame from the `stack` field of the `MException`.

Tips

Valid escape sequences for the msgString argument 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.

Examples

Example 1 — Formatted Messages

If your message string requires formatting specifications like those used with the sprintf function, you can use this syntax to compose the error message string:

exception = MException(msgIdent, msgString, v1, v2, ...)

For example,

exception = MException('AcctError:Incomplete', ...
      'Field ''%s.%s'' is not defined.', ...
      'Accounts', 'ClientName');

exception.message
ans =
    Field 'Accounts.ClientName' is not defined.

Example 2

The catch block in this example checks to see if the specified file could not be found. If this is the case, the program allows for the possibility that a common variation of the filename extension (e.g., jpeg instead of jpg) was used by retrying the operation with a modified extension. This is done using a try-catch statement that is nested within the original try-catch.

function d_in = read_image(filename)
[path name ext] = fileparts(filename);
try
   fid = fopen(filename, 'r'); 
   d_in = fread(fid); 
catch exception

   % Did the read fail because the file could not be found?
   if ~exist(filename, 'file')

      % Yes. Try modifying the filename extension.
      switch ext
      case '.jpg'    % Change jpg to jpeg 
          altFilename = strrep(filename, '.jpg', '.jpeg')
      case '.jpeg'   % Change jpeg to jpg 
          altFilename = strrep(filename, '.jpeg', '.jpg')
      case '.tif'    % Change tif to tiff 
          altFilename = strrep(filename, '.tif', '.tiff')
      case '.tiff'   % Change tiff to tif 
          altFilename = strrep(filename, '.tiff', '.tif')
      otherwise 
         rethrow(exception);
      end 

      % Try again, with modifed filename.
      try
         fid = fopen(altFilename, 'r'); 
         d_in = fread(fid);
      catch
         rethrow(exception)
      end 
   end 
end

Example 3 — Nested try-catch

This example attempts to open a file in a folder that is not on the MATLAB path. It uses a nested try-catch block to give the user the opportunity to extend the path. If the file still cannot be found, the program issues an exception with the first error appended to the second:

function data = read_it(filename);
try
   % Attempt to open and read from a file.
   fid = fopen(filename, 'r');
   data = fread(fid);
catch exception1
   % If the error was caused by an invalid file ID, try 
   % reading from another location.
   if strcmp(exception1.identifier, 'MATLAB:FileIO:InvalidFid')
      msg = sprintf( ...
         '\nCannot open file %s. Try another location?  ', ...
         filename);
      reply = input(msg, 's')
      if reply(1) == 'y'
          newFolder = input('Enter folder name:  ', 's');
      else
          throw(exception1);
      end
      oldpath = addpath(newFolder);
      try
         fid = fopen(filename, 'r');
         data = fread(fid);
      catch exception2
         exception3 = addCause(exception2, exception1)
         path(oldpath);
         throw(exception3);
      end
      path(oldpath);
   end
end
fclose(fid);

If you run this function in a try-catch block at the command line, you can look at the MException object by assigning it to a variable (e) with the catch command.