How to Set and Debug Exception Breakpoints in Safari Web Inspector

When developing complex JavaScript applications, runtime errors often occur unexpectedly—such as TypeError: undefined is not an object or unhandled promise rejections. In asynchronous single-page applications, by the time an error surfaces in the console, the execution context and call stack that produced the defect have already been destroyed, making it difficult to determine the root cause. Setting manual breakpoints throughout codebases is tedious and impractical when chasing intermittent crashes. Exception Breakpoints in Safari Web Inspector solve this problem by instructing the WebKit JavaScript runtime to pause execution automatically at the exact line and moment an exception is thrown, before error recovery or state corruption occurs. This article demonstrates how to configure, filter, and debug Exception Breakpoints in Safari Web Inspector.

Understanding Exception Breakpoints in WebKit

Unlike standard breakpoints that halt execution based on line numbers or event handlers, Exception Breakpoints hook directly into WebKit’s JavaScriptCore exception handling subsystem. When an error is thrown—either via a native runtime fault or an explicit throw new Error() statement—WebKit checks your breakpoint configuration before unwinding the stack.

Safari Web Inspector provides two primary exception handling modes:

• Uncaught Exceptions (Default): Pauses execution only when an exception is thrown that is not surrounded by a try...catch block. These represent true fatal errors that would otherwise terminate script execution or trigger window.onerror.
• All Exceptions: Pauses execution on every single thrown exception, regardless of whether it is caught and handled gracefully by application logic. This mode is useful for diagnosing third-party libraries that silently swallow errors or rethrow corrupted state.

Enabling Web Inspector and Navigating to the Debugger

To use Exception Breakpoints in Safari on macOS:

1. Ensure developer features are enabled by navigating to Safari > Settings > Advanced and checking Show features for web developers.
2. Open your target website or application in Safari.
3. Right-click anywhere on the webpage and select Inspect Element (or press Cmd + Option + I).
4. Click the Sources tab in the Web Inspector top navigation bar (or select the Debugger instrument).
5. In the left-hand navigation sidebar, look for the Breakpoints section.

Configuring and Arming Exception Breakpoints

At the top of the Breakpoints sidebar, locate the dedicated Exceptions toggle control:

1. Look for the hexagonal pause icon representing exception breakpoints in the Breakpoints panel header.
2. Click the icon or select the All Exceptions / Uncaught Exceptions dropdown menu:
   • Don’t Pause on Exceptions (Grey Icon): The debugger ignores all thrown errors.
   • Pause on Uncaught Exceptions (Blue Outline): The debugger pauses only when an unhandled error threatens to terminate execution. This is the recommended setting for general debugging.
   • Pause on All Exceptions (Filled Blue): The debugger halts on every single error throw across the entire runtime.
3. Confirm that the desired breakpoint mode is active by observing the visual state of the breakpoint icon.

Stepping Through Exceptions and Inspecting the Call Stack

With an Exception Breakpoint armed, reproduce the application crash or trigger the interaction that generates the fault. Safari immediately halts execution at the throwing statement:

1. Paused Line: The source code viewer highlights the exact statement that triggered the exception, marked with a red warning badge.
2. Inspecting the Error Object: In the Scope Chain sidebar on the right, inspect the thrown exception object (typically named exception or error). Expand the object to review its message string, error name, and custom metadata.
3. Tracing the Call Stack: Review the Call Stack panel. Because execution paused before the stack was unwound, you can click on any parent frame in the stack trace to examine the local variables, function arguments, and component state that led up to the failure.
4. Console Evaluation: Switch to the interactive Console panel. Since the JavaScript runtime is paused in the exact scope of the error, you can evaluate variables and test potential fixes directly within the execution context.
5. Resuming Execution: Press F8 (or Cmd + /) to continue execution, or use Step Over (F10) to observe how an enclosing catch block processes the error.

Ignoring Handled Third-Party Library Exceptions

When running in All Exceptions mode, modern web applications that utilize polyfills, feature-detection routines, or libraries (such as Babel, Webpack, or jQuery) often trigger dozens of benign, caught exceptions during initial page load.

To prevent these routine checks from interrupting your debugging session:

1. Right-click the vendor or polyfill script in the Sources navigator (e.g. vendor.bundle.js).
2. Select Blackbox Script (or Ignore Program in modern WebKit releases). Safari will automatically suppress exception pausing inside ignored files, pausing only when your application code throws an error.
3. Alternatively, revert to Uncaught Exceptions mode so that handled internal library checks execute without pausing.

By using Exception Breakpoints in Safari Web Inspector, web developers can diagnose elusive JavaScript crashes instantly, capturing full stack context before state is lost.