Set Breakpoints

Setting breakpoints pauses the execution of your MATLAB® program so that you can examine values where you think a problem might be. You can set breakpoints using the Editor or by using functions in the Command Window.

There are three types of breakpoints:

  • Standard breakpoints

  • Conditional breakpoints

  • Error breakpoints

You can set breakpoints only at executable lines in saved files that are in the current folder or in folders on the search path. You can set breakpoints at any time, whether MATLAB is idle or busy running a file.

By default, MATLAB automatically opens files when it reaches a breakpoint. To disable this option:

  1. From the Home tab, in the Environment section, click Preferences.

    The Preferences dialog box opens.

  2. Select MATLAB > Editor/Debugger.

  3. Clear the Automatically open file when MATLAB reaches a breakpoint option and click OK.

    Note:   Debugging using the graphical debugger is not supported in live scripts. For more information, see What Is a Live Script?

Standard Breakpoints

A standard breakpoint stops at a specified line in a file. You can set a standard breakpoint using these methods:

  • Click 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. Executable lines are indicated by a — (dash) in the breakpoint alley. If an executable statement spans multiple lines, you can set a breakpoint at each line in that statement, even though the additional lines do not have a — (dash) in the breakpoint alley. For example, in this code, you can set a breakpoint at all four lines:

    If you attempt to set a breakpoint at a line that is not executable, such as a comment or a blank line, MATLAB sets it at the next executable line.

  • Use the dbstop function. For example, to add a breakpoint at line 2 in a file named myprogram.m, type:

    dbstop in myprogram at 2
    MATLAB adds a breakpoint at line 2 in the function myprogram.

To examine values at increments in a for loop, set the breakpoint within the loop, rather than at the start of the loop. If you set the breakpoint at the start of the for loop, and then step through the file, MATLAB stops at the for statement only once. However, if you place the breakpoint within the loop, MATLAB stops at each pass through the loop.

Conditional Breakpoints

A conditional breakpoint causes MATLAB to stop at a specified line in a file only when the specified condition is met. Use conditional breakpoints when you want to examine results after some iterations in a loop.

You can set a conditional breakpoint from the Editor or Command Window:

  • Editor— Right-click the breakpoint alley at an executable line where you want to set the breakpoint and select Set/Modify Condition.

    When the Editor dialog box opens, enter a condition and click OK. A condition is any valid MATLAB expression that returns a logical scalar value.

    As noted in the dialog box, MATLAB evaluates the condition before running the line. For example, suppose that you have a file called myprogram.m.

    Add a breakpoint with the following condition at line 6:

    n >= 4
    A yellow, conditional breakpoint icon appears in the breakpoint alley at that line.

  • Command Window — Use the dbstop function. For example, to add a conditional breakpoint in myprogram.m at line 6 type:

    dbstop in myprogram at 6 if n>=4

When you run the file, MATLAB enters debug mode and pauses at the line when the condition is met. In the myprogram example, MATLAB runs through the for loop twice and pauses on the third iteration at line 6 when n is 4. If you continue executing, MATLAB pauses again at line 6 on the fourth iteration when n is 5.

Error Breakpoints

An error breakpoint causes MATLAB to stop program execution and enter debug mode if MATLAB encounters a problem. Unlike standard and conditional breakpoints, you do not set these breakpoints at a specific line in a specific file. When you set an error breakpoint, MATLAB stops at any line in any file if the error condition specified occurs. MATLAB then enters debug mode and opens the file containing the error, with the execution arrow at the line containing the error.

To set an error breakpoint, on the Editor tab, click Breakpoints and select from these options:

  • Stop on Errors to stop on all errors.

  • Stop on Warnings to stop on all warnings.

  • More Error and Warning Handling Options to open the Stop if Errors/Warnings for All Files dialog box where you can choose among more options.

You also can set an error breakpoint programmatically. For more information, see dbstop.

Advanced Error Breakpoint Configuration

To further configure error breakpoints, use the Stop if Error/Warning for All Files dialog box. On the Editor tab, click Breakpoints and select More Error and Warning Handling Options. Each tab in the dialog box details a specific type of error breakpoint:

  • Errors

    If 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 that produced the error. You cannot resume execution.

  • Try/Catch Errors

    If an error occurs in a try...catch block, execution pauses. MATLAB enters debug mode and opens the file to the line in the try portion of the block that produced the error. You can resume execution or step through the file using additional debugging features.

  • Warnings

    If a warning occurs, execution pauses. MATLAB enters debug mode and opens the file to the line that produced the warning. You can resume execution or step through the file using additional debugging features.

  • NaN or Inf

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

You can select the state of each error breakpoint in the dialog box:

  • Never stop... clears the error breakpoint of that type.

  • Always stop... adds an error breakpoint of that type.

  • Use message identifiers... adds a limited error breakpoint of that type. Execution stops only for the error you specify with the corresponding message identifier.

    You can add multiple message identifiers, and then edit or remove them.

      Note:   This option is not available for the NaN or Inf type of error breakpoint.

    To 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 MATLAB to stop. The identifier is of the form component:message (for example, MATLAB:narginchk:notEnoughInputs).

    5. Click OK.

      The message identifier you specified appears in the list of identifiers.

The function equivalent appears to the right of each option. For example, the function equivalent for Always stop if error is dbstop if error.

Obtain 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

To obtain a warning message identifier generated by a MATLAB function, run the function to produce the warning. Then, run this command:

[m,id] = lastwarn
MATLAB returns the last warning identifier to id. An example of a warning message identifier is MATLAB:concatenation:integerInteraction.

Breakpoints in Anonymous Functions

You can set multiple breakpoints in a line of MATLAB code that contains anonymous functions. For example, you can set a breakpoint for the line itself, where MATLAB software pauses at the start of the line. Or, alternatively, you can set a breakpoint for each anonymous function in the 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 that line.

To view information about all the breakpoints on a line, hover your pointer on the breakpoint icon. A tooltip appears with available information. For example, in this code, line 5 contains two anonymous functions, with a breakpoint at each one. The tooltip tells us that both breakpoints are enabled.

When you set a breakpoint in an anonymous function, MATLAB pauses when the anonymous function is called. A green arrow shows where the code defines the anonymous function. A white arrow shows where the code calls the anonymous functions. For example, in this code, MATLAB pauses the program at a breakpoint set for the anonymous function sqr, at line 2 in a file called myanonymous.m. The white arrow indicates that the sqr function is called from line 3.

Invalid Breakpoints

A gray breakpoint indicates an invalid breakpoint.

Breakpoints are invalid for these reasons:

  • There are unsaved changes in the file. To make breakpoints valid, save the file. The gray breakpoints become red, indicating that they are now valid.

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

Disable Breakpoints

You can disable selected breakpoints so that your program temporarily ignores them and runs uninterrupted. For example, you might disable a breakpoint after you think you identified and corrected a problem, or if you are using conditional breakpoints.

To disable a breakpoint, right-click the breakpoint icon, and select Disable Breakpoint from the context menu.

An X appears through the breakpoint icon to indicate that it is disabled.

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

Breakpoint on line 6 has conditional expression 'false'.

To reenable a breakpoint, right-click the breakpoint icon and select Enable Breakpoint from the context menu.

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

Clear Breakpoints

All breakpoints remain in a file until you clear (remove) them or until they are cleared automatically at the end of your MATLAB session.

Too clear a breakpoint, use either of these methods:

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

  • Use the dbclear function. For example, to clear the breakpoint at line 6 in a file called myprogram.m, type

     dbclear in myprogram at 6

To clear all breakpoints in all files:

  • Place your cursor anywhere in a breakpoint line. Click Breakpoints, and select Clear All.

  • Use the dbclear all command. For example, to clear all the breakpoints in a file called myprogram.m, type

    dbclear all in myprogram

Breakpoints clear automatically when you end a MATLAB session. To save your breakpoints for future sessions, see the dbstatus function.

Related Examples

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support