Auto Layout Debugging
When to Use This Skill
Use when:
- Seeing "Unable to simultaneously satisfy constraints" errors in console
- Views positioned incorrectly or not appearing
- Constraint warnings during app launch or navigation
- Ambiguous layout errors
- Views appearing at unexpected sizes
- Debug View Hierarchy shows misaligned views
- Storyboard/XIB constraints behaving differently at runtime
Overview
Core Principle: Auto Layout constraint errors follow predictable patterns. Systematic debugging with proper tools identifies issues in minutes instead of hours.
Time Savings: Typical constraint debugging without this workflow: 30-60 minutes. With systematic approach: 5-10 minutes.
Quick Decision Tree
Constraint error in console?
├─ Can't identify which views?
│ └─ Use Symbolic Breakpoint + Memory Address Identification
├─ Constraint conflicts shown?
│ └─ Use Constraint Priority Resolution
├─ Ambiguous layout (multiple solutions)?
│ └─ Use _autolayoutTrace to find missing constraints
└─ Views positioned incorrectly but no errors?
└─ Use Debug View Hierarchy + Show Constraints
Understanding Constraint Error Messages
Anatomy of Error Message
Unable to simultaneously satisfy constraints.
Probably at least one of the constraints in the following list you don't need.
(
"<NSLayoutConstraint:0x7f8b9c6... 'UIView-Encapsulated-Layout-Width' ... (active)>",
"<NSLayoutConstraint:0x7f8b9c5... UILabel:0x7f8b9c4... .width == 300 (active)>",
"<NSLayoutConstraint:0x7f8b9c3... UILabel:0x7f8b9c4... .leading == ... + 20 (active)>",
"<NSLayoutConstraint:0x7f8b9c2... ... .trailing == UILabel:0x7f8b9c4... .trailing + 20 (active)>"
)
Will attempt to recover by breaking constraint
<NSLayoutConstraint:0x7f8b9c5... UILabel:0x7f8b9c4... .width == 300 (active)>
Key Components:
- Memory addresses —
0x7f8b9c4... identifies views and constraints
- Visual Format — Human-readable constraint description
(active) status — Constraint is currently enforced- Recovery action — Which constraint system will break (usually lowest priority)
System-Generated Constraints
UIView-Encapsulated-Layout-Width/Height:
- Created by UIKit for cells, system views
- Often source of conflicts
- Usually correct; your constraints are the problem
Autoresizing Mask Constraints:
- Format:
h=--& or v=&--
- = fixed dimension& = flexible dimension- Example:
h=--& = fixed left margin and width, flexible right margin
Debugging Workflow
Step 1: Set Up Symbolic Breakpoint (One-Time Setup)
Purpose: Break when constraint conflict occurs, before system breaks constraint.
Setup:
- Open Breakpoint Navigator (⌘+7 or ⌘+8)
- Click
+ → "Symbolic Breakpoint"
- Symbol:
UIViewAlertForUnsatisfiableConstraints
- (Optional) Add Action → "Sound" → select sound
- (Optional) Check "Automatically continue after evaluating actions"
Why this works: Pauses execution at exact moment of constraint conflict, giving you debugger access to all views and constraints.
Step 2: Identify Views from Memory Addresses
When breakpoint hits, console shows memory addresses like UILabel:0x7f8b9c4...
Technique 1: Use %rbx Register (When Breakpoint Hits)
# Print all involved views and constraints
po $arg1
# Or on older Xcode versions
po $rbx
Output: NSArray containing all conflicting constraints and affected views.
Technique 2: Set View Background Color
# Set background color on suspected view
expr ((UIView *)0x7f8b9c4...).backgroundColor = [UIColor redColor]
# Continue execution to see which view turned red
Result: Visually identifies which view corresponds to memory address.
Technique 3: Print View Hierarchy
Objective-C projects:
po [[UIWindow keyWindow] _autolayoutTrace]
Swift projects:
expr -l objc++ -O -- [[UIWindow keyWindow] _autolayoutTrace]
Output: Entire view hierarchy with * marking ambiguous layouts.
Example:
*<UIView:0x7f8b9c4...>
| <UILabel:0x7f8b9c3...>
The * indicates this UIView has ambiguous constraints.
Technique 4: Print Constraints for Specific View
# Horizontal constraints (axis: 0)
po [0x7f8b9c4... constraintsAffectingLayoutForAxis:0]
# Vertical constraints (axis: 1)
po [0x7f8b9c4... constraintsAffectingLayoutForAxis:1]
Output: All constraints affecting that view's layout.
Step 3: Use Debug View Hierarchy
When to use: Views positioned incorrectly, constraints not visible in code.
Workflow:
- Trigger the issue — Navigate to screen with constraint problems
- Pause execution — Click "Debug View Hierarchy" button in debug bar (or Debug → View Debugging → Capture View Hierarchy)
- Inspect 3D view — Rotate view hierarchy to see layering
- Enable "Show Constraints" — Shows all constraints as lines
- Select view — Right panel shows all constraints affecting selected view
Key Features:
- Show Clipped Content — Reveals views positioned off-screen
- Show Constraints — Visualizes constraint relationships
- Filter Bar — Search for specific views by class or memory address
Finding Issues:
- Purple constraints = satisfied
- Orange/red constraints = conflicts
- Select constraint → see both views it connects
Step 4: Name Your Constraints (Prevention)
Why: Makes error messages readable instead of cryptic memory addresses.
In Interface Builder (Storyboards/XIBs)
- Select constraint in Document Outline
- Open Attributes Inspector
- Set Identifier field (e.g., "ProfileImageWidthConstraint")
Before:
<NSLayoutConstraint:0x7f8b9c5... UILabel:0x7f8b9c4... .width == 300 (active)>
After:
<NSLayoutConstraint:0x7f8b9c5... 'ProfileImageWidthConstraint' UILabel:0x7f8b9c4... .width == 300 (active)>
Programmatically
let widthConstraint = imageView.widthAnchor.constraint(equalToConstant: 100)
widthConstraint.identifier = "ProfileImageWidthConstraint"
widthConstraint.isActive = true
Impact: Instantly know which constraint is breaking without hunting through code.
Step 5: Name Your Views (Prevention)
Why: Error messages show view class AND your custom label.
In Interface Builder
- Select view in Document Outline
- Open Identity Inspector
- Set Label field (e.g., "Profile Image View")
Before:
<UIImageView:0x7f8b9c4... (active)>
After:
<UIImageView:0x7f8b9c4... 'Profile Image View' (active)>
Programmatically
imageView.accessibilityIdentifier = "ProfileImageView"
Note: Xcode automatically uses textual components (UILabel text, UIButton titles) as identifiers when available.
Common Constraint Conflict Patterns
Pattern 1: Conflicting Fixed Widths
Symptom:
Container width: 375
Child width: 300
Child leading: 20
Child trailing: 20
// 20 + 300 + 20 = 340 ≠ 375
❌ WRONG:
imageView.widthAnchor.constraint(equalToConstant: 300).isActive = true
imageView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 20).isActive = true
imageView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -20).isActive = true
✅ CORRECT Option 1 (Remove fixed width):
imageView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 20).isActive = true
imageView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -20).isActive = true
✅ CORRECT Option 2 (Use priorities):
let widthConstraint = imageView.widthAnchor.constraint(equalToConstant: 300)
widthConstraint.priority = .defaultHigh
widthConstraint.isActive = true
imageView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 20).isActive = true
imageView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -20).isActive = true
Pattern 2: UIView-Encapsulated-Layout Conflicts
Symptom: Table cells or collection view cells conflicting with UIView-Encapsulated-Layout-Width.
Why it happens: System sets cell width based on table/collection view. Your constraints fight it.
❌ WRONG:
contentLabel.widthAnchor.constraint(equalToConstant: 320).isActive = true
✅ CORRECT:
contentLabel.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: 16).isActive = true
contentLabel.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -16).isActive = true
Pattern 3: Autoresizing Mask Conflicts
Symptom: Mixing Auto Layout with autoresizingMask or not setting translatesAutoresizingMaskIntoConstraints = false.
❌ WRONG:
let imageView = UIImageView()
view.addSubview(imageView)
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true
✅ CORRECT:
let imageView = UIImageView()
imageView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(imageView)
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true
Why: translatesAutoresizingMaskIntoConstraints = true creates automatic constraints that conflict with your explicit constraints.
Pattern 4: Ambiguous Layout (Missing Constraints)
Symptom: View appears, but position shif
