Documentation Center

  • Trial Software
  • Product Updates

Debugging Process and Features

Ways to Debug MATLAB Files

You can debug MATLAB® files using the Editor, which is a graphical user interface, as well as by using debugging functions from the Command Window. You can use both methods interchangeably. These topics and the example describe both methods.

Preparing for Debugging

Do the following to prepare for debugging:

  1. Open the file — To use the Editor for debugging, open it with the file to run.

  2. Save changes — If you are editing the file, save the changes before you begin debugging. If you try to run a file with unsaved changes from within the Editor, the file is automatically saved before it runs. If you run a file with unsaved changes from the Command Window, MATLAB software runs the saved version of the file. Therefore, you do not see the results of your changes.

  3. Add the files to a folder on the search path or put them in the current folder. Be sure the file you run and any files it calls are in folders that are on the search path. If all required files are in the same folder, you can instead make that folder the current folder.

Debugging Example — The Collatz Problem

The debugging process and features are best described using an example. To prepare to use the example, create two files, collatz.m and collatzplot.m, that produce data for the Collatz problem.

For any given positive integer, n, the Collatz algorithm produces a sequence of integers. If n equals 1, the sequence is complete. Otherwise, if n is odd, multiply it by 3 and add 1 to get the next integer in the sequence. Otherwise, if n is even, divide it by 2 to get the next integer in the sequence. Repeat the process until the sequence terminates with 1. The number of integers in the sequence varies depending on the starting value, n.

The Collatz conjecture is that the sequence always terminates within a finite number of steps. The files for this example are useful for studying the behavior of the Collatz algorithm. The file collatz.m generates the Collatz sequence of integers for any given n. The file collatzplot.m plots the length of the sequence against the starting value for all starting values from 1 through a given value m. The plot shows patterns that you can study further.

Following are the results when n is 1, 2, or 3.

n

Sequence

Number of Integers in the Sequence

1

1

1

2

2  1

2

3

3  10  5  16  8  4  2  1

8

Files for the Collatz Problem.  Following are the two files you use for the debugging example. To create these files on your system, open two new files. Select and copy the following code from the Help browser and paste it into the files. Save and name the files collatz.m and collatzplot.m. Save them to your current folder or add the folder where you save them to the search path. One of the files has an embedded error to illustrate the debugging features.

Open the files by issuing the following commands, and then saving each file to a local folder:

open(fullfile(matlabroot,'help','techdoc','matlab_env',...
	'examples','collatz.m'))
open(fullfile(matlabroot,'help','techdoc','matlab_env',...
	'examples','collatzplot.m'))

Trial Run for the Example.  Open the file collatzplot.m. Make sure that the current folder is the folder in which you saved collatzplot.

Try out collatzplot to see if it works correctly. Use a simple input value, for example, 3, and compare the results to those shown in the preceding table. Typing

collatzplot(3)

produces the plot shown in the following figure.

The plot for n = 1 appears to be correct—for 1, the Collatz series is 1, and contains one integer. But for n = 2 and n = 3, it is wrong. There should be only one value plotted for each integer, the number of integers in the sequence, which the preceding table shows to be 2 (for n = 2) and 8 (for n = 3). Instead, multiple values are plotted. Use MATLAB debugging features to isolate the problem.

Set Breakpoints

Set breakpoints to pause execution of the MATLAB file so you can examine values where you think the problem can be. You can set breakpoints using the Editor, using functions in the Command Window, or both.

There are three basic types of breakpoints you can set in MATLAB files:

  • A standard breakpoint, which stops at a specified line in a file. For details, see Set Standard Breakpoints.

  • A conditional breakpoint, which stops at a specified line in a file only under specified conditions. For details, see Conditional Breakpoints.

  • An error breakpoint that stops in any file when it produces the specified type of warning, error, or NaN or infinite value. For details, see Error Breakpoints.

You can disable standard and conditional breakpoints so that MATLAB temporarily ignores them, or you can remove them. For details, see Disable and Clear Breakpoints. Breakpoints do not persist after you exit the MATLAB session.

You can only set valid standard and conditional breakpoints at executable lines in saved files that are in the current folder or in folders on the search path. When you add or remove a breakpoint in a file that is not in a folder on the search path or in the current folder, a dialog box appears. This dialog box presents options that allow you to add or remove the breakpoint. You can either change the current folder to the folder containing the file, or you can add the folder containing the file to the search path.

Do not set a breakpoint at a for statement if you want to examine values at increments in the loop. For example, in

for n = 1:10 
    m = n+1; 
end 

MATLAB executes the for statement only once, which is efficient. Therefore, when you set a breakpoint at the for statement and step through the file, you only stop at the for statement once. Instead place the breakpoint at the next line, m=n+1 to stop at each pass through the loop.

You cannot set breakpoints while MATLAB is busy, for example, running a file, unless that file is paused at a breakpoint.

Set Standard Breakpoints

To set a standard breakpoint using the Editor:

  1. If you have changed the file, save it.

  2. Either:

    • Click in the breakpoint alley at an executable line where you want to set the breakpoint. The breakpoint alley is the narrow column on the left side of the Editor, to the right of the line number.

    • Position the cursor in an executable line. On the Editor tab, in the Breakpoints section, click Breakpoints, and then select Set/Clear.

      Executable lines are preceded by a - (dash). If you attempt to set breakpoints at lines that are not executable, such as comments or blank lines, MATLAB sets it at the next executable line.

Set Breakpoints for the Example.  It is unclear whether the problem in the example is in collatzplot or collatz. To start, follow these steps:

  1. In collatzplot.m, click the dash in the breakpoint alley at line 9 to set a breakpoint.

    This breakpoint enables you to step into collatz to see if the problem is there.

  2. Set additional breakpoints at lines 10 and 11.

    These breakpoints stop the program so you can examine the interim results.

Valid (Red) and Invalid (Gray) Breakpoints.  Red breakpoints indicate valid standard breakpoints.

Breakpoints are gray for either of these reasons:

  • There are unsaved changes in the file. Save the file to make breakpoints valid. The gray breakpoints become red, indicating they are now valid. Any gray breakpoints that you entered at invalid breakpoint lines automatically move to the next valid breakpoint line with a successful file save.

  • There is a syntax error in the file. When you set a breakpoint, an error message appears indicating where the syntax error is. Fix the syntax error and save the file to make breakpoints valid.

Function Alternative for Setting Breakpoints

To set a breakpoint using the debugging functions, use dbstop. For the example, type:

dbstop in collatzplot at 9
dbstop in collatzplot at 10
dbstop in collatzplot at 11

Run a File with Breakpoints

After setting breakpoints, run the file from the Command Window or the Editor.

Run the Example

For the example, run collatzplot for the simple input value, 3, by typing the following in the Command Window:

collatzplot(3)

The example, collatzplot, requires an input argument and therefore runs only from the Command Window or from the input value(s) specified on the Run drop-down list on the Editor tab.

Results of Running a File Containing Breakpoints

Running the file results in the following:

  • The prompt in the Command Window changes to

    K>>

    indicating that MATLAB is in debug mode.

  • The program pauses at the first breakpoint. This means that line will be executed when you continue. The pause is indicated in the Editor by the green arrow just to the right of the breakpoint. In the example, the pause is at line 9 of collatzplot, as shown here:

    The line at which you are paused displays in the Command Window. For the example:

  • The function the Function Call Stack field displays on the Editor tab changes to reflect the current function (sometimes referred to as the caller or calling workspace). The call stack includes local functions as well as called functions. If you use debugging functions from the Command Window, use dbstack to view the current call stack.

  • If the file you are running is not in the current folder or a folder on the search path, you are prompted to either add the folder to the path or change the current folder.

In debug mode, you can set breakpoints, step through programs, examine variables, and run other functions.

MATLAB software could become nonresponsive if it stops at a breakpoint while displaying a modal dialog box or figure that your file creates. In that event, press Ctrl+C to go to the MATLAB prompt.

Step Through a File

While debugging, you can step through a MATLAB file, pausing at points where you want to examine values.

Use any of the following methods:

  • Click Step, Step In, Step Out in Editor tab.

  • Use the dbstep or dbcont function

Details about these debugging buttons appear in the following table.

Toolbar Button

Debug Menu Item

Description

Function Alternative

Run to Cursor

Continue execution of file until the line where the cursor is positioned. Also available on the context menu.

None

Step

Execute the current line of the file.

dbstep

Step In

Execute the current line of the file and, if the line is a call to another function, step into that function.

dbstep in

ContinueResume execution of file until completion or until another breakpoint is encountered.

dbcont

Step Out

After stepping in, run the rest of the called function or local function, leave the called function, and pause.

dbstep out

Quit Debugging

Exit debug mode.

dbquit out

Continue Running in the Example

In the example, collatzplot is paused at line 9. Because the problem results are correct for N/n = 1, continue running until N/n = 2. Click Continue three times to move through the breakpoints at lines 9, 10, and 11. Now the program is again paused at the breakpoint at line 9.

Step into the Called Function in the Example

Now that collatzplot is paused at line 9 during the second iteration, click Step In or type dbstep in in the Command Window to step into collatz and walk through that file. Stepping into line 9 of collatzplot goes to line 9 of collatz. If collatz is not open in the Editor, it automatically opens if you have selected Automatically open files when MATLAB reaches a breakpoint in the Preference dialog box.

The pause indicator at line 9 of collatzplot changes to a hollow arrow , indicating that MATLAB control is now in a local function called from the main program. The call stack shows that the current function is now collatz.

In the called function, collatz in the example, you can do the same things you can do in the main (calling) function—set breakpoints, run, step through, and examine values.

Examine Values

While the program is paused, you can view the value of any variable currently in the workspace. Examine values when you want to see whether a line of code has produced the expected result or not. If the result is as expected, continue running or step to the next line. If the result is not as you expect, then that line, or a previous line, contains an error. Use the following methods to examine values:

Many of these methods are used in Examine Values in the Example.

Select the Workspace

Variables assigned through the Command Window and created using scripts are considered to be in the base workspace. Variables created in a function belong to their own function workspace. To examine a variable, you must first select its workspace. When you run a program, the current workspace is shown in the Function Call Stack field. To examine values that are part of another workspace for a currently running function or for the base workspace, first select that workspace from the list in the Function Call Stack field.

If you use debugging functions from the Command Window:

  • To display the call stack, use dbstack.

  • To change to a different workspace, use dbup and dbdown.

  • To list the variables in the current workspace, use who or whos.

Workspace in the Example.  At line 9 of collatzplot, you stepped in, and the current line is 9 in collatz. The Function Call Stack field shows that collatz is the current workspace.

View Values as Data Tips in the Editor

To view the current value of a variable in the Editor, first enable datatips, then use the mouse to display a datatip:

  1. On the Home tab, in the Environment section, click Preferences, and select MATLAB > Editor/Debugger > Display.

  2. Select Enable datatips in edit mode under General display options.

  3. In the Editor, position the mouse pointer to the left of a variable.

    The variable's current value appears in a data tip. The data tip stays in view until you move the pointer. If you have trouble getting the data tip to appear, click in the line containing the variable, and then move the pointer next to the variable.

View Values in the Command Window

You can examine values while in debug mode at the K>> prompt. To see the variables currently in the workspace, use who. Type a variable name in the Command Window and it displays the variable's current value. For the example, to see the value of n, type

n

The Command Window displays the expected result

n =

     2

and displays the debug prompt, K>>.

View Values in the Workspace Browser and Variables Editor

You can view the value of variables in the Value column of the Workspace browser. The Workspace browser displays all variables in the current workspace. To change to another workspace and view its variables, use Function Call Stack drop-down list on the Editor tab, in the Debug section.

The Value column does not show all details for all variables. To see details, double-click a variable in the Workspace browser. The Variables Editor opens, displaying the content for that variable. You can open the Variables Editor directly for a variable using openvar.

To see the value of n in the Variables Editor for the example, type

openvar n

and the Variables Editor opens, showing that n = 1 as expected.

Evaluate a Selection

Select a variable or equation in a MATLAB file in the Editor. Right-click and select Evaluate Selection from the context menu (for a single-button mouse, press Ctrl+click). The Command Window displays the value of the variable or equation. You cannot evaluate a selection while MATLAB is busy, for example, running a file.

Examine Values in the Example

Step from line 9 through line 13 in collatz. Step again, and the pause indicator jumps to line 17, just after the if loop, as expected. Step again, to line 18, check the value of sequence in line 17 and see that the array is

2  1

as expected for n = 2. Step again, which moves the pause indicator from line 18 to line 11. At line 11, step again. Because next_value is now 1, the while loop ends. The pause indicator is at line 11 and appears as a green down arrow . This indicates that processing in the called function is complete and program control will return to the calling program. Step again from line 11 in collatz and execution is now paused at line 9 in collatzplot.

Note that instead of stepping through collatz, the called function, as was just done in this example, you can step out from a called function back to the calling function, which automatically runs the rest of the called function and returns to the next line in the calling function. To step out, use the Step Out button or type dbstep out in the Command Window.

In collatzplot, step again to advance to line 10, and then to line 11. The variable seq_length in line 10 is a vector with the elements:

1  2

which is correct.

Finally, step again to advance to line 12. Examining the values in line 11, N = 2 as expected, but the second variable, plot_seq, has two values, where only one value is expected. While the value for plot_seq is as expected:

2  1

it is the incorrect variable for plotting. Instead, seq_length(N) should be plotted.

Problems Viewing Variable Values from the Parent Workspace

Sometimes, if you set a breakpoint in a function, and then attempt to view the value of a variable in the parent workspace using the dbup command, the value of the variable is currently under construction. Therefore, the value is not available. This is true whether you view the value by specifying the dbup command in the Command Window or by using the Function Call Stack field on the Editor tab.

In such cases, MATLAB returns the following message, where x is the variable for which you are trying to examine the value:

K>> x
Reference to a called function result under construction x. 

For example, suppose you have code such as the following:

x = collatz(x);

MATLAB detects that the evaluation of collatz(x) replaces the input variable, x. To optimize memory use, MATLAB overwrites the memory that x currently occupies to hold a new value for x. When you request the value of x, and it is under construction, its value is not available, and MATLAB displays the error message.

Correct Problems and End Debugging

The following are some of the ways to correct problems and end the debugging session:

Complete the Example uses many of these features.

Change Values and Check Results

While debugging, you can change the value of a variable in the current workspace to see if the new value produces expected results. While the program is paused, assign a new value to the variable in the Command Window, Workspace browser, or Variables Editor. Then continue running or stepping through the program. If the new value does not produce the expected results, the program has a different problem.

End Debugging

After identifying a problem, end the debugging session. You must end a debugging session if you want to change and save a file to correct a problem, or if you want to run other functions in MATLAB.

    Note   Quit debug mode before editing a file. If you edit a file while in debug mode, you can get unexpected results when you run the file. If you do edit a file while in debug mode, breakpoints turn gray, indicating that results might not be reliable. See Valid (Red) and Invalid (Gray) Breakpoints for details.

    If you attempt to save an edited file while in debug mode, a dialog box opens allowing you to exit debug mode and save the file.

To end debugging, click Quit Debugging, or use the function dbquit.

After quitting debugging, pause indicators in the Editor display no longer appear, and the normal prompt >> appears in the Command Window instead of the debugging prompt, K>>. You can no longer access the call stack.

Disable and Clear Breakpoints

Disable a breakpoint to ignore it temporarily. Clear a breakpoint to remove it.

Disable and Enable Breakpoints.  You can disable selected breakpoints so the program temporarily ignores them and runs uninterrupted, for example, after you think you identified and corrected a problem. This is especially useful for conditional breakpoints—see Conditional Breakpoints.

To disable a breakpoint, do one of the following:

  • Right-click the breakpoint icon, and select Disable Breakpoint from the context menu.

  • Place your cursor anywhere in a breakpoint line. Click Breakpoints, and selectEnable/Disable from the drop-down list.

To disable a conditional breakpoint, use either of the methods in the preceding list. An X appears through the breakpoint icon as shown here.

When you run dbstatus, the resulting message for a disabled breakpoint is

Breakpoint on line 9 has conditional expression 'false'.

After disabling a breakpoint, you can re-enable it to make it active again or you can clear it.

To re-enable a breakpoint, do either of the following:

  • Right-click the breakpoint icon and select Enable Breakpoint from the context menu.

  • Place your cursor anywhere in a breakpoint line. Click Breakpoints, and selectEnable/Disable from the drop-down list.

The X no longer appears on the breakpoint icon and program execution will pause at that line.

Clear (Remove) Breakpoints.  All breakpoints remain in a file until you clear (remove) them or until they are cleared automatically. Clear a breakpoint after determining that a line of code is not causing a problem.

To clear a breakpoint in the Editor:

  • Right-click the breakpoint icon and select Clear Breakpoint from the context menu.

  • Place your cursor anywhere in a breakpoint line. Click Breakpoints, and selectSet/Clear from the drop-down list.

  • Use the dbclear in file at lineno command in the Command Window. For the example, clear the breakpoint at line 9 in collatzplot by typing:

     dbclear in collatzplot at 9

To clear all breakpoints in all files:

  • Place your cursor anywhere in a breakpoint line. Click Breakpoints, and selectClear All from the drop-down list.

  • Use dbclear all in the Command Window.

    For the example, clear all of the breakpoints in collatzplot by typing:

    dbclear all in collatzplot

Breakpoints clear automatically when you:

  • End the MATLAB session.

  • Clear the file using clear name or clear all.

    Note   When clear name or clear all is in a statement in a file that you are debugging, it clears the breakpoints.

Save Breakpoints

You can use the s=dbstatus syntax and then save s to save the current breakpoints to a MAT-file. At a later time, you can load s and restore the breakpoints using dbstop(s). For more information, including an example, see the dbstatus reference page.

Correct Problems in a MATLAB File

To correct a problem in a MATLAB file:

  1. Quit debugging.

    Do not modify a file while MATLAB is in debug mode. If you do, breakpoints turn gray, indicating that results might not be reliable. See Valid (Red) and Invalid (Gray) Breakpoints for details.

  2. Modify the file.

  3. Save the file.

  4. Set, disable, or clear breakpoints, as appropriate.

  5. Run the file again to be sure that it produces the expected results.

Complete the Example

To correct the problem in the example:

  1. End the debugging session. One way to do this is to click Quit Debugging

  2. In collatzplot.m line 11, change the string plot_seq to seq_length(N) and save the file.

  3. Clear the breakpoints in collatzplot.m. One way to do this is by typing

    dbclear all in collatzplot

    in the Command Window.

  4. Run collatzplot for m = 3 by typing

    collatzplot(3)

    in the Command Window.

  5. Verify the result. The figure shows that the length of the Collatz series is 1 when n = 1, 2 when n = 2, and 8 when n = 3, as expected.

  6. Test the function for a slightly larger value of m, such as 6, to be sure that the results are still accurate. To make it easier to verify collatzplot for m = 6 as well as the results for collatz, add this line at the end of collatz.m

    sequence
    

    which displays the series in the Command Window. The results for when n = 6 are

    sequence =
    
         6     3    10     5    16     8     4     2     1

    Then run collatzplot for m = 6 by typing

    collatzplot(6)
    
  7. To make debugging easier, you ran collatzplot for a small value of m. Now that you know it works correctly, run collatzplot for a larger value to produce more interesting results. Before doing so, you consider disabling output for the line you just added in step 6, line 19 of collatz.m, by adding a semicolon to the end of the line so it appears as

    sequence;

    Then run

    collatzplot(500)

    The following figure shows the lengths of the Collatz series for n = 1 through n = 500.

Run Parts in MATLAB Files That Have Unsaved Changes

It is a good practice to modify a MATLAB file after you quit debugging, and then save the modification and run the file. Otherwise, you might get unexpected results. However, there are situations where you want to experiment during debugging. Perhaps you want to modify a part of the file that has not yet run, and then run the remainder of the file without saving the change. Follow these steps:

  1. While stopped at a breakpoint, modify a part of the file that has not yet run.

    Breakpoints turn gray, indicating they are invalid.

  2. Select all of the code after the breakpoint, right-click, and then select Evaluate Selection from the context menu.

You can also use code sections to do this.

Conditional Breakpoints

Set conditional breakpoints to cause MATLAB to stop at a specified line in a file only when the specified condition is met. One particularly good use for conditional breakpoints is when you want to examine results after a certain number of iterations in a loop. For example, set a breakpoint at line 10 in collatzplot, specifying that MATLAB stop only if N is greater than or equal to 2. This section covers the following topics:

Set Conditional Breakpoints

To set a conditional breakpoint:

  1. Click in the line where you want to set the conditional breakpoint.

  2. Click Breakpoints on the Editor tab, and select Set Condition. If a standard breakpoint exists at that line, use this same method to make it conditional.

    The MATLAB Editor conditional breakpoint dialog box opens.

  3. Type a condition in the dialog box, where a condition is any valid MATLAB expression that returns a logical scalar value. Click OK. As noted in the dialog box, the condition is evaluated before running the line. For the example, at line 9 in collatzplot, enter the following as the condition:

    N>=2

    A yellow breakpoint icon (indicating the breakpoint is conditional) appears in the breakpoint alley at that line.

When you run the file, MATLAB software enters debug mode and pauses at the line only when the condition is met. In the collatzplot example, MATLAB runs through the for loop once and pauses on the second iteration at line 9 when N is 2. If you continue executing, MATLAB pauses again at line 9 on the third iteration when N is 3.

Modify, Disable, or Clear Conditional Breakpoints

The following table describes how to adjust conditional breakpoints.

ToDo This
Modify a condition for a breakpoint in the current line.

Right-click the conditional breakpoint icon, and then from the context menu, select Set/Modify Condition.

Disable a conditional breakpoint.Click the associated conditional breakpoint icon.
Clear a conditional breakpoint.Double-click the associated conditional breakpoint icon.

Function Alternatives for Manipulating Conditional Breakpoints

The following table lists the functions available for adjusting conditional breakpoints from the Command Window.

ToUse This Function
Set a conditional breakpoint.dbstop
Clear a conditional breakpoint.dbclear
View a list of currently set breakpoints, including the conditional expression for each conditional breakpoint. dbstatus

Breakpoints in Anonymous Functions

You can set multiple breakpoints in a line of MATLAB code that contains anonymous functions. You can do both of the following:

  • Set a breakpoint for the line itself (MATLAB software pauses at the start of the line).

  • Set a breakpoint for each anonymous function in that line.

When you add a breakpoint to a line containing an anonymous function, the Editor asks where in the line you want to add the breakpoint. If there is more than one breakpoint in a line, the breakpoint icon is blue, regardless of the status of any of the breakpoints on the line.

To display information in a tooltip about all breakpoints on a line, position the pointer on the blue icon.

To perform a breakpoint action for a line that can contain multiple breakpoints, such as Clear Breakpoint, right-click the breakpoint alley at that line, and then select the action.

When you set a breakpoint in an anonymous function, MATLAB pauses when the anonymous function is called.

The following illustration shows the Editor when you set a breakpoint in the anonymous function sqr in line 2, and then run the file. When you run the file, MATLAB pauses each time that the anonymous function sqr executes. The green arrow shows where the code defines sqr. The white arrow, on line 5, indicates where the code calls sqr.

Breakpoints in Methods That Overload Functions

MATLAB functions often call other MATLAB functions and methods to perform their operations. If you set a breakpoint in a class method, and then run a MATLAB function that results in calling that method, execution stops at the breakpoint. This behavior can be confusing if you are unaware that the MATLAB function calls the method containing the breakpoint.

For instance, suppose you do the following:

  1. Define a class named MyClass that overloads the MATLAB size function.

  2. Create an instance of MyClass.

  3. Insert breakpoints within the MyClass size method.

  4. Call whos.

When you call the whos function, it calls the size function to obtain size information about the variables in the workspace. Under the preceding circumstances, because MyClass overloads the size function, whos calls the MyClass size method instead of the default size function to determine the size of the MyClass object. Execution stops at the breakpoint you set in the size method. You can enable the MATLAB function to execute to completion by either stepping or continuing through the method. To prevent this behavior from recurring, remove the breakpoints.

Error Breakpoints

Set error breakpoints to stop program execution and enter debug mode when MATLAB encounters a problem. Unlike standard and conditional breakpoints, you do not set these breakpoints at a specific line in a specific file. Rather, once set, MATLAB stops at any line in any file when the error condition specified by using the error breakpoint occurs. MATLAB then enters debug mode and opens the file containing the error, with the pause indicator at the line containing the error. Files open only when you select Automatically open file when MATLAB reaches a breakpoint under MATLAB > Editor/Debugger in the Preferences dialog box. Error breakpoints remain in effect until you clear them or until you end the MATLAB session. This section covers the following topics:

Set and Clear Error Breakpoints

To set error breakpoints:

  1. On the Editor tab, in the Breakpoints section, click Breakpoints.

  2. Select:

    • Stop on Errors to stop on all errors.

    • Stop on Warnings to stop on all warnings.

    • More Error and Warning Handling Options for additional options. This opens the Stop if Errors/Warnings for All Files dialog box

      To clear error breakpoints, select the Never stop if ... option for all appropriate tabs, and then click OK.

Error Breakpoint Types and Options

As the tabs in the Stop if Errors/Warnings for All Files dialog box suggest, there are four basic types of error breakpoints you can set:

  • Errors

    When an error occurs, execution stops, unless the error is in a try...catch block. MATLAB enters debug mode and opens the file to the line in the try portion of the block that produced the error. You cannot resume execution.

  • Try/Catch Errors

    When an error occurs in a try...catch block, execution pauses. MATLAB enters debug mode and opens the file to the line that produced the error. You can resume execution or use debugging features.

  • Warnings

    When a warning occurs, MATLAB pauses, enters debug mode, and opens the file, paused at the line that produced the warning. You can resume execution or use debugging features.

  • NaN or Inf

    When an operator, function call, or scalar assignment produces a NaN (not-a-number) or Inf (infinite) value, MATLAB pauses, enters debug mode, and opens the file. MATLAB pauses immediately after the line that encountered the value. You can resume execution or use debugging features.

Select options for these error breakpoints:

  • Click Never stop... on a tab to clear that type of breakpoint.

  • Click Always stop... on a tab to set that type of breakpoint.

  • Select Use message identifiers... on a tab to limit each type of error breakpoint (except NaN or Inf). Execution stops only for the error you specify by the corresponding message identifier.

    This option is not available for the NaN or Inf type of error breakpoint. You can add multiple message identifiers, and edit or remove them.

Examples of Setting Warning and Error Breakpoints

Pausing Executing for Warnings.  To pause execution when MATLAB produces a warning:

  1. Click the Warnings tab.

  2. Click Always stop if warning, and then click OK.

Now, when you run a file and MATLAB produces a warning, execution pauses and MATLAB enters debug mode. The file opens in the Editor at the line that produced the warning.

Set Breakpoints for a Specific Error.  To stop execution for a specific error add a message identifier:

  1. Click the Errors, Try/Catch Errors, or Warnings tab.

  2. Click Use Message Identifiers.

  3. Click Add.

  4. In the resulting Add Message Identifier dialog box, type the message identifier of the error for which you want to stop. The identifier is of the form component:message (for example, MATLAB:narginchk:notEnoughInputs). Then click OK.

    The message identifier you specified appears in the Stop if Errors/Warnings for All Files dialog box.

  5. Click OK.

Obtain Error Message Identifiers.  To obtain an error message identifier generated by a MATLAB function, run the function to produce the error, and then call MExeption.last. For example:

surf
MException.last

The Command Window displays the MException object, including the error message identifier in the identifier field. For this example, it displays:

ans = 

  MException

  Properties:
    identifier: 'MATLAB:narginchk:notEnoughInputs'
       message: 'Not enough input arguments.'
         cause: {}
         stack: [1x1 struct]

  Methods

Obtain Warning Message Identifiers.  To obtain a warning message identifier generated by a MATLAB function, run the function to produce the warning. Then, run:

[m,id] = lastwarn

MATLAB returns the last warning identifier to id. An example of a warning message identifier is MATLAB:concatenation:integerInteraction.

Function Alternative for Manipulating Error Breakpoints

The function equivalent for each option in the Stop if Errors/Warnings for All Files dialog box, appears to the right of each option. For example, the function equivalent for Always stop if error is dbstop if error. Use these functions in the Command Window as listed in the following table.

ToUse This Function
Set error breakpoints.dbstop
Clear error breakpoints.dbclear
View a list of currently set breakpoints, including the condition and message identifier for each error breakpoint.dbstatus

Was this topic helpful?