iOS Auto Layout Debugging: How to Trap UIViewAlertForUnsatisfiableConstraints Errors

The Challenge of Debugging Auto Layout Constraint Conflicts

In iOS development, Auto Layout is a powerful interface layout system, but debugging constraint conflicts can be challenging. When the system detects unsatisfiable constraints, it outputs messages like the following in the debugger log:

Will attempt to recover by breaking constraint 
<NSLayoutConstraint:0x191f0920 H:[MPKnockoutButton:0x17a876b0]-(34)-[MPDetailSlider:0x17a8bc50](LTR)>

Make a symbolic breakpoint at UIViewAlertForUnsatisfiableConstraints to catch this in the debugger.
The methods in the UIConstraintBasedLayoutDebugging category on UIView listed in <UIKit/UIView.h> may also be helpful.

This message suggests setting a symbolic breakpoint to trap UIViewAlertForUnsatisfiableConstraints calls, but this function doesn't appear directly in user code, making debugging difficult.

Setting Up Symbolic Breakpoints

The most effective way to catch these constraint conflicts is using Xcode's symbolic breakpoint feature. Here are the specific steps:

1. Open the Breakpoint Navigator (shortcut cmd+7, or cmd+8 in Xcode 9 and later).
2. Click the Add button in the lower left corner.
3. Select Add Symbolic Breakpoint....
4. Enter UIViewAlertForUnsatisfiableConstraints in the Symbol field.

Once configured, the debugger will pause at this breakpoint whenever the system encounters constraint conflicts, allowing developers to inspect the current state.

Enhancing Debug Information

Merely pausing execution isn't enough—we need more information to locate problems. You can add custom actions to the breakpoint to output detailed Auto Layout trace information. The configuration differs based on project language:

For Objective-C projects, add this action:

po [[UIWindow keyWindow] _autolayoutTrace]

For Swift projects, due to language differences, use this more complex expression:

expr -l objc++ -O -- [[UIWindow keyWindow] _autolayoutTrace]

These commands output the complete view hierarchy of the current window, marking views with layout issues. The output uses specific symbols to indicate different situations:

• * - Views laid out with Auto Layout
• + - Manually laid out views with translatesAutoresizingMaskIntoConstraints = YES
• • - Layout engine hosts

Problematic views are marked as MISSING HOST CONSTRAINTS or AMBIGUOUS LAYOUT, showing specific constraint IDs.

Practical Debugging Techniques

After obtaining Auto Layout trace information, you can use debugging commands to visualize problems. For example, to highlight problematic views, modify their background color when the debugger pauses:

In Objective-C:

expr ((UIView *)0x7f88a8cc2050).backgroundColor = [UIColor redColor]

In Swift 3.0 and later:

expr -l Swift -- import UIKit
expr -l Swift -- unsafeBitCast(0x7f88a8cc2050, to: UIView.self).backgroundColor = UIColor.red

The address 0x7f88a8cc2050 should be replaced with the actual memory address of the problematic view. This approach immediately shows marked views on the device or simulator, greatly simplifying problem localization.

Debugging Workflow Summary

The complete debugging workflow is as follows:

1. Set a symbolic breakpoint for UIViewAlertForUnsatisfiableConstraints in Xcode.
2. Configure the appropriate _autolayoutTrace output action based on project language.
3. Run the application until the breakpoint triggers.
4. Analyze the Auto Layout trace output to find marked problematic views.
5. Use memory addresses to modify view properties (like background color) for visual confirmation.
6. Adjust constraints or view configurations based on identified issues.

This method works not only for obvious constraint conflicts but also helps discover potential issues causing ambiguous layouts.

Advanced Debugging Recommendations

Beyond the basic approach, several advanced techniques can further improve debugging efficiency:

• Save symbolic breakpoint configurations as shared breakpoints for team collaboration.
• Add conditions to breakpoints to trigger only for specific views or scenarios.
• Combine with other methods from the UIConstraintBasedLayoutDebugging category, such as exerciseAmbiguityInLayout to test ambiguous layouts.
• For complex interfaces, consider using UIView's constraintsAffectingLayoutForAxis: method to check constraints in specific directions.

Through systematic debugging methods, developers can more effectively resolve Auto Layout problems, improving application interface stability and consistency.