Warning Control

Overview

The MATLAB software gives you the ability to control what happens when a warning is encountered during program execution. Options that are available include

• Display selected warnings.

• Ignore selected warnings.

• Stop in the debugger when a warning is invoked.

• Display the stack trace after a warning is invoked.

Depending on how you set your warning controls, you can have these actions affect all warnings in your code, specific warnings that you select, or just the most recently invoked warning.

Setting up this system of warning control involves several steps.

1. Start by determining the scope of the control you need for the warnings generated by your code. Do you want the control operations to affect all the warnings in your code at once, or do you want to be able to control certain warnings separately?

2. If the latter is true, you will need to identify those warnings you want to selectively control. This requires going through your code and attaching unique message identifiers to each of those warnings. If, on the other hand, you do not require that fine a granularity of control, the warning statements in your code need no message identifiers.

3. When you are ready to run your programs, use the MATLAB warning control statements to exercise the desired controls on all or selected warnings. Include message identifiers in these control statements when selecting specific warnings to act upon.

Back to Top

Warning Statements

The warning statements you put into your code must contain the string to be displayed when the warning is incurred, and may also contain a message identifier. If you are not planning to use warning control or if you do not need to single out certain warnings for control, you need to specify only the message string. Use the syntax shown in Warnings. Valid formats are

warning('warnmsg')
warning('formatted_warnmsg', arg1, arg2, ...)

Attaching an Identifier to the Warning Statement

If you want to be able to apply control statements to specific warnings, you need to include a message identifier in the warning statements you wish to control. The message identifier must be the first argument in the statement. Valid formats are

warning('msg_id', 'warnmsg')
warning('msg_id', 'formatted_warnmsg', arg1, arg2, ...)

See Message Identifiers for information on how to specify the msg_id argument.

Note   When you specify more than one input argument with warning, MATLAB treats the warnmsg string as if it were a formatted_warnmsg. This is explained in Formatted Message Strings.

Back to Top

Warning Control Statements

Once you have the warning statements in your program file and are ready to execute it, you tell MATLAB how to act on these warnings by issuing control statements. These statements place the specified warning(s) into a desired state and have the format

warning state msg_id

Control statements can return information on the state of selected warnings if you assign the output to a variable, as shown below. See Output from Control Statements.

s = warning('state', 'msg_id');

Warning States

There are three possible values for the state argument of a warning control statement.

Message Identifiers

In addition to the message identifiers already discussed, there are three other identifiers that you can use in control statements only.

Note   MATLAB starts up with all warnings enabled, except for those displayed in response to the command, warning('query', 'all').

When warnings are disabled, the dbstop if warning commands have no effect. If warnings are disabled for specific message identifiers, the dbstop if warning identifier has no effect for those identifiers.

Retrieving a Message Identifier from a Warning.  If you get a warning and you would like to know what the message identifier is for that warning, you can retrieve the identifier from the second output of the lastwarn function. The following example generates a warning when it attempts to concatenate two unlike integer types together:

warning on all;

A = [int8(150), int16(300)];
Warning: Concatenation with dominant (left-most) integer class
   may overflow other operands on conversion to return class.

If you are already aware of the consequences of this command and do not want to see this warning message displayed every time you run your program, you can disable the warning message. To identify the warning to disable, use the following commands to acquire the message identifier:

warnStruct = warning('query', 'last');
msgid_integerCat = warnStruct.identifier
msgid_integerCat =
   MATLAB:concatenation:integerInteraction

Once you have the identifier, you can use it to disable this one particular message:

warning('off', msgid_integerCat);

Try the command again

A = [int8(150), int16(300)]
A =
  127  127

Turn the message back on again, if you need to, as shown here:

warning('on', msgid_intcatwarn);
MATLAB:nonScalarConditional

Enabling and Disabling Selected Warnings.  Enable just the actionNotTaken warning from Simulink by first turning off all warnings and then setting just that warning to on.

warning off all
warning on Simulink:actionNotTaken

Next, use query to determine the current state of all warnings. It reports that you have set all warnings to off, with the exception of Simulink:actionNotTaken.

warning query all
The default warning state is 'off'. Warnings not set to the 
default are

  State  Warning Identifier

     on  Simulink:actionNotTaken

Enabling and Disabling All Warnings.  You can enable or disable all warnings using the 'all' identifier. Using the query option shows the result:

warning on all

warning query all
The default warning state is 'on'. Warnings not set to the 
default are

  State  Warning Identifier

    off  MATLAB:nonScalarConditional

Note that, in this case, there is one warning that does not take on the default state when that state is changed from off to on. This is intentional. If so desired, you can force this or any individual warning to either the on or off state by specifying the message identifier in the command:

warning on MATLAB:nonScalarConditional

warning query all
   All warnings have the state 'on'.

Disabling the Most Recent Warning.  Evaluating inv on zero displays a warning message. Turn off the most recently invoked warning with warning off last.

inv(0)
Warning: Matrix is singular to working precision.
ans =
   Inf

warning off last

inv(0)              % No warning is displayed this time
ans =
   Inf

Back to Top

Output from Control Statements

The warning function, when used in a control statement, returns a MATLAB structure array containing the previous state of the selected warning(s). Use the following syntax to return this information in structure array s:

s = warning('state', 'msg_id');

You must type the command using the MATLAB function format; parentheses and quotation marks are required.

Note   MATLAB does not display warning output if you do not assign the output to a variable.

The next example turns off InconsistentDataType warnings for the MATLAB:odearguments component, and returns the identifier and previous state in a 1-by-1 structure array.

MATLAB:odearguments:InconsistentDataType

s = warning('off','MATLAB:odearguments:InconsistentDataType')
s = 
    identifier: 'MATLAB:odearguments:InconsistentDataType'
         state: 'on'

You can use output variables with any type of warning control statement. If you just want to collect the information but do not want to change state, simply perform a query on the warning(s). MATLAB returns the current state of those warnings selected by the message identifier.

s = warning('query', 'msg_id');

If you want to change state, but save the former state so you can restore it later, use the return structure array to save that state. The following example does an implicit query, returning state information in s, and then turns on all warnings.

s = warning('on', 'all');

See Saving and Restoring State, for more information on restoring the former state of warnings.

Output Structure Array

Each element of the structure array returned by warning contains two fields.

If you query for the state of just one warning, using a message identifier or 'last' in the command, MATLAB returns a one-element structure array. The identifier field contains the selected message identifier, and the state field holds the current state of that warning:

s = warning('query','last')
s = 
   identifier: 'MATLAB:odearguments:InconsistentDataType'
        state: 'on'

If you query for the state of all warnings, using 'all' in the command, MATLAB returns a structure array having one or more elements:

• The first element of the array always represents the default state. (This is the state set by the last warning on|off all command.)

• Each other element of the array represents a warning that is in a state different from the default.

  warning off all
  warning on MATLAB:odearguments:InconsistentDataType
  warning on MATLAB:rmpath:DirNotFound
  
  s = warning('query', 'all')
  s = 
     3x1 struct array with fields:
         identifier
         state
  
  s(1)
  ans = 
     identifier: 'all'
          state: 'off'
  
  s(2)
  ans = 
      identifier: 'MATLAB:odearguments:InconsistentDataType'
           state: 'on'
  s(3)
  ans = 
      identifier: 'MATLAB:rmpath:DirNotFound'
           state: 'on'
  

Back to Top

Saving and Restoring State

To temporarily change the state of some warnings and then later return to your original settings, save the original state in a structure array and then restore it from that array. You can save and restore the state of all of your warnings or just one that you select with a message identifier.

To save the current warning state, assign the output of a warning control statement, as discussed in Output from Control Statements. The following statement saves the current state of all warnings in structure array s:

s = warning('query', 'all');

To restore state from s, use the syntax shown below. Note that the MATLAB function format (enclosing arguments in parentheses) is required.

warning(s)

Example 1 — Performing an Explicit Query

Perform a query of all warnings to save the current state in structure array s:

s = warning('query', 'all');

Then, after doing some work that includes making changes to the state of some warnings, restore the original state of all warnings:

warning(s)

Example 2 — Performing an Implicit Query

Turn on one particular warning, saving the previous state of this warning in s. Remember that this nonquery syntax (where state equals on or off) performs an implicit query prior to setting the new state:

s = warning('on', 'Control:parameterNotSymmetric');

Restore the state of that one warning when you are ready, with

warning(s)

Back to Top

Backtrace and Verbose Modes

In addition to warning messages, there are two modes that can be enabled or disabled with a warning control statement. These modes are shown here.

The syntax for this type of control statement is as follows, where state, in this case, can be only on, off, or query:

warning state mode

Note that there is no need to include a message identifier with this type of control statement. All enabled warnings are affected by the this type of control statement.

Note   You cannot save and restore the current state of the backtrace or verbose modes as you can with other states.

Example 1 — Enabling Verbose Warnings

When you enable verbose warnings, MATLAB displays an extra line of information with each warning that tells you how to suppress it:

Turn on all warnings, disable backtrace (if you have just run the previous example), and enable verbose warnings:

warning on all
warning off backtrace
warning on verbose

Create a function that tests a condition and displays a warning message based on the input:

function testArrayMax(arr, max)
exceedMax = find(arr > max);
if any(exceedMax)
    warning('TestEnv:InvalidInput', ...
        'Values in array "%s" exceed the maximum.', ...
        inputname(1))
end

Call the function to find out how to suppress warnings that might be generated by that function. Note the last line displayed here:

A = [1287, 5010, 2759];

testArrayMax(A, 5000)
Warning: Values in array "A" exceed the maximum.
(Type "warning off TestEnv:InvalidInput" to suppress this warning.) 

Use the message identifier TestEnv:InvalidInput to disable only this warning, and run the function again. This time the warning message is not displayed:

warning off TestEnv:InvalidInput
testArrayMax(A, 5000)

Example 2 — Displaying a Stack Trace on a Specific Warning

It can be difficult to locate the source of a warning when it is generated from code buried in several levels of function calls. This example generates a warning within a function that is nested several levels deep within the primary function in file isValidArray.m:

function isValidArray(A)
max = 5000;
nestFun_1
    function nestFun_1
        nestFun_2
        function nestFun_2
            testArrayMax(A, max);
        end
    end
end

After enabling all warnings, run the program. Due to the value of A(2), the function generates a warning:

warning on all
warning off verbose

A = [1287, 5010, 2759];

isValidArray(A)
Warning: Values in array "A" exceed the maximum. 

In a function of this size, it is not difficult to find the cause of the warning, but in a file of several hundred lines, this could take some time. To simplify the debug process, enable backtrace mode. In this mode, MATLAB reports which function generated the warning (testArrayMax), the line number of the attempted operation (line 4), the sequence of function calls that led up to the execution of the function (from isValidArray to nestFun_1 to nestFun_2 and finally to testArrayMax), and the line at which each of these function calls were made (3, 5, 7, and 4):

warning on backtrace

callArrayMax(A)
Warning: Values in array "A" exceed the maximum. 
> In testArrayMax at 4
  In isValidArray>nestFun_1/nestFun_2 at 7
  In isValidArray>nestFun_1 at 5
  In isValidArray at 3

Back to Top

Warnings

Debugging Errors and Warnings

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit