Programming and Data Types

Handling and Recovering from an Error

The catch segment of a try-catch block needs to effectively handle any errors that may be caught by the preceding try. Frequently, you will want to simply report the error and stop execution. This prevents erroneous data from being propagated into the remainder of the program.

Reporting an Error

To report an error and halt program execution, use the MATLAB error function. You determine what the error mesage will be by specifying it as an input to the error function in your code. For example,

• if n < 1
      error('n must be 1 or greater.')
  end
  

displays the message shown below when n is equal to zero.

• ??? n must be 1 or greater.
  

Formatted Message Strings.   The error message string that you specify can also contain formatting conversion characters, such as those used with the MATLAB sprintf function. Make the error string the first argument, and then add any variables used by the conversion as subsequent arguments.

• error('formatted_errormsg', arg1, arg2, ...)
  

For example, if your program cannot find a specific file, you might report the error with

• error('File %s not found', filename);
  

Message Identifiers.   Use a message identifier argument with error to attach a unique tag to that error message. MATLAB uses this tag to better identify the source of an error. The first argument in this example is the message identifier.

• error('MATLAB:noSuchFile', 'File "%s" not found', ...
         filename);
  

See Using Message Identifiers with lasterr for more information on how to use identifiers with errors.

Formatted String Conversion.   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 is 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.
  

Identifying an Error

Once an error has been caught, you will need to know the source of the error in order to handle it appropriately. The lasterr function returns information that enables you to identify the error that was most recently generated by MATLAB.

To return the most recent error message to the variable errormsg, type

• errormsg = lasterr;
  

You can also change the text of the last error message with a new message or with an empty string as shown below. You might want to do this if a lower level routine detects an error that you don't want visible to the upper levels.

• lasterr('newerrormsg');   % Replace last error with new string
  lasterr('');              % Replace last error with empty string
  

Example.   The matrix_multiply function shown earlier in this section could fail for various reasons. If it is called with incompatible matrices, for example, lasterr returns the following string.

• lasterr
  ans =
     Error using ==> *
     Inner matrix dimensions must agree.
  

This example uses lasterr to determine the cause of an error in matrix_multiply.

• function matrix_multiply(A, B)
  try
     A * B
  catch
     errmsg = lasterr;
     if(strfind(errmsg, 'Inner matrix dimensions'))
        disp('** Wrong dimensions for matrix multiply')
     else
        if(strfind(errmsg, 'not defined for variables of class'))
           disp('** Both arguments must be double matrices')
        end
     end
  end
  

When calling the function with two matrices not compatible for matrix multiplication, you get the following error message.

• A = [1  2  3; 6  7  2; 0  1  5];
  B = [9  5  6; 0  4  9];
  matrix_multiply(A, B)
  ** Wrong dimensions for matrix multiply
  

When calling the function with a cell array argument, you get a message that addresses that error.

• C = {9 5 6; 0 4 9};
  matrix_multiply(A, C)
  ** Both arguments must be double matrices
  

Regenerating an Error

Use the rethrow function to regenerate an error that has previously been thrown. You may want to do this from the catch part of a try-catch block, for example, after performing some required cleanup tasks following an error.

This is how you would rethrow an error in a try-catch block:

• try
     do_something
  catch
     do_cleanup
     rethrow(err)
  end
  

rethrow generates an error based on the err input argument that you provide. This argument must be a MATLAB structure with at least the following two fields.

Fieldname	Description
message	Text of the error message
identifier	Message identifier of the error message

If you simply want to regenerate the last error that occurred, the lasterror function returns a structure that can then be passed directly to rethrow.

Note    lasterror is not the same as lasterr. The lasterror return structure contains the message string and message identifier for the last error, and may contain more information in future versions of MATLAB. The lasterr return string arguments contain only the message string and identifier.

Errors and Warnings

Warnings