Use when encountering "Unable to simultaneously satisfy constraints" errors, constraint conflicts, ambiguous layout warnings, or views positioned incorrectly - systematic debugging workflow for Auto Layout issues in iOS
/plugin marketplace add CharlesWiltgen/Axiom/plugin install axiom@axiom-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Use when:
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.
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
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:
0x7f8b9c4... identifies views and constraints(active) status — Constraint is currently enforcedUIView-Encapsulated-Layout-Width/Height:
Autoresizing Mask Constraints:
h=--& or v=&--- = fixed dimension& = flexible dimensionh=--& = fixed left margin and width, flexible right marginPurpose: Break when constraint conflict occurs, before system breaks constraint.
Setup:
+ → "Symbolic Breakpoint"UIViewAlertForUnsatisfiableConstraintsWhy this works: Pauses execution at exact moment of constraint conflict, giving you debugger access to all views and constraints.
When breakpoint hits, console shows memory addresses like UILabel:0x7f8b9c4...
# Print all involved views and constraints
po $arg1
# Or on older Xcode versions
po $rbx
Output: NSArray containing all conflicting constraints and affected views.
# 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.
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.
# Horizontal constraints (axis: 0)
po [0x7f8b9c4... constraintsAffectingLayoutForAxis:0]
# Vertical constraints (axis: 1)
po [0x7f8b9c4... constraintsAffectingLayoutForAxis:1]
Output: All constraints affecting that view's layout.
When to use: Views positioned incorrectly, constraints not visible in code.
Workflow:
Key Features:
Finding Issues:
Why: Makes error messages readable instead of cryptic memory addresses.
Before:
<NSLayoutConstraint:0x7f8b9c5... UILabel:0x7f8b9c4... .width == 300 (active)>
After:
<NSLayoutConstraint:0x7f8b9c5... 'ProfileImageWidthConstraint' UILabel:0x7f8b9c4... .width == 300 (active)>
let widthConstraint = imageView.widthAnchor.constraint(equalToConstant: 100)
widthConstraint.identifier = "ProfileImageWidthConstraint"
widthConstraint.isActive = true
Impact: Instantly know which constraint is breaking without hunting through code.
Why: Error messages show view class AND your custom label.
Before:
<UIImageView:0x7f8b9c4... (active)>
After:
<UIImageView:0x7f8b9c4... 'Profile Image View' (active)>
imageView.accessibilityIdentifier = "ProfileImageView"
Note: Xcode automatically uses textual components (UILabel text, UIButton titles) as identifiers when available.
Symptom:
Container width: 375
Child width: 300
Child leading: 20
Child trailing: 20
// 20 + 300 + 20 = 340 ≠ 375
❌ WRONG:
// Conflicting constraints
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
// Over-constrained: width + leading + trailing = 3 horizontal constraints (only need 2)
✅ CORRECT Option 1 (Remove fixed width):
// Let width be calculated from leading + trailing
imageView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 20).isActive = true
imageView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -20).isActive = true
// Width will be container width - 40
✅ CORRECT Option 2 (Use priorities):
let widthConstraint = imageView.widthAnchor.constraint(equalToConstant: 300)
widthConstraint.priority = .defaultHigh // 750 (can be broken if needed)
widthConstraint.isActive = true
imageView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 20).isActive = true
imageView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -20).isActive = true
// Required constraints (1000) will break lower-priority width constraint if needed
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:
// In UITableViewCell
contentLabel.widthAnchor.constraint(equalToConstant: 320).isActive = true
// Conflicts with system-determined cell width
✅ CORRECT:
// Use relative constraints, not fixed widths
contentLabel.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: 16).isActive = true
contentLabel.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -16).isActive = true
// Width adapts to cell width automatically
Symptom: Mixing Auto Layout with autoresizingMask or not setting translatesAutoresizingMaskIntoConstraints = false.
❌ WRONG:
let imageView = UIImageView()
view.addSubview(imageView)
// Forgot to disable autoresizing mask
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true
// Conflicts with autoresizing mask constraints
✅ CORRECT:
let imageView = UIImageView()
imageView.translatesAutoresizingMaskIntoConstraints = false // ← CRITICAL
view.addSubview(imageView)
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true
Why: translatesAutoresizingMaskIntoConstraints = true creates automatic constraints that conflict with your explicit constraints.
Symptom: View appears, but position shifts unexpectedly or _autolayoutTrace shows * (ambiguous).
Problem: Not enough constraints to determine unique position/size.
❌ WRONG (Ambiguous X position):
imageView.topAnchor.constraint(equalTo: view.topAnchor, constant: 20).isActive = true
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true
imageView.heightAnchor.constraint(equalToConstant: 100).isActive = true
// Missing: horizontal position (leading/trailing/centerX)
✅ CORRECT:
imageView.topAnchor.constraint(equalTo: view.topAnchor, constant: 20).isActive = true
imageView.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true // ← Added
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true
imageView.heightAnchor.constraint(equalToConstant: 100).isActive = true
Rule: Every view needs:
Symptom: Unexpected constraint breaks, but all constraints seem correct.
Problem: Multiple constraints at same priority competing.
❌ WRONG:
// Both required (priority 1000)
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true
imageView.widthAnchor.constraint(greaterThanOrEqualToConstant: 150).isActive = true
// Impossible: width can't be 100 AND >= 150
✅ CORRECT:
let preferredWidth = imageView.widthAnchor.constraint(equalToConstant: 100)
preferredWidth.priority = .defaultHigh // 750
preferredWidth.isActive = true
let minWidth = imageView.widthAnchor.constraint(greaterThanOrEqualToConstant: 150)
minWidth.priority = .required // 1000
minWidth.isActive = true
// Result: width will be 150 (required constraint wins)
Priority levels (higher = stronger):
.required (1000) — Must be satisfied.defaultHigh (750) — Strong preference.defaultLow (250) — Weak preferenceUse case: View that should be certain size, but can shrink if needed.
// Preferred size: 200x200
let widthConstraint = imageView.widthAnchor.constraint(equalToConstant: 200)
widthConstraint.priority = .defaultHigh // 750
widthConstraint.isActive = true
let heightConstraint = imageView.heightAnchor.constraint(equalToConstant: 200)
heightConstraint.priority = .defaultHigh // 750
heightConstraint.isActive = true
// But never smaller than 100x100
imageView.widthAnchor.constraint(greaterThanOrEqualToConstant: 100).isActive = true
imageView.heightAnchor.constraint(greaterThanOrEqualToConstant: 100).isActive = true
// And never larger than container
imageView.widthAnchor.constraint(lessThanOrEqualTo: containerView.widthAnchor).isActive = true
imageView.heightAnchor.constraint(lessThanOrEqualTo: containerView.heightAnchor).isActive = true
Result: Image is 200x200 when space available, shrinks to fit container (min 100x100).
Content Hugging (resist expanding):
// Label should not stretch beyond its text width
label.setContentHuggingPriority(.defaultHigh, for: .horizontal)
Compression Resistance (resist shrinking):
// Label should not truncate if possible
label.setContentCompressionResistancePriority(.required, for: .horizontal)
Common pattern:
// In horizontal stack: priorityLabel (hugs) + spacer + valueLabel (hugs)
priorityLabel.setContentHuggingPriority(.defaultHigh, for: .horizontal)
valueLabel.setContentHuggingPriority(.defaultHigh, for: .horizontal)
// Spacer fills remaining space (low hugging priority)
spacerView.setContentHuggingPriority(.defaultLow, for: .horizontal)
Problem: View transformations (rotate, scale) don't affect Auto Layout.
Gotcha:
imageView.transform = CGAffineTransform(rotationAngle: .pi / 4) // 45° rotation
// Auto Layout still uses original (un-rotated) frame for calculations
Solution: Auto Layout works correctly, but visual debugging can be confusing. Use original frame for constraint debugging.
Check:
UIViewAlertForUnsatisfiableConstraintsSolution 1: Use background color technique
expr ((UIView *)0x7f8b9c4...).backgroundColor = [UIColor redColor]
continue
Solution 2: Print recursive description
po [0x7f8b9c4... recursiveDescription]
Solution 3: Check view's class
po [0x7f8b9c4... class]
Check:
Check:
Wrong: Seeing constraint warning, continuing anyway.
Correct: Fix every constraint warning immediately. They compound and cause unpredictable layout later.
Wrong: Debugging constraints by memory address.
Correct: Always set constraint identifiers. 30 seconds now saves 30 minutes later.
Wrong: Setting leading + trailing + width.
Correct: Use 2 of 3 (leading + trailing, OR leading + width, OR trailing + width).
Wrong:
imageView.frame = CGRect(x: 50, y: 50, width: 100, height: 100) // Manual frame
imageView.widthAnchor.constraint(equalToConstant: 100).isActive = true // Auto Layout
Correct: Choose one approach. If using Auto Layout, set translatesAutoresizingMaskIntoConstraints = false and let constraints determine position/size.
Before (no systematic approach):
After (systematic debugging):
axiom-xcode-debugging skillaxiom-swiftui-performance skillaxiom-ui-testing skillDocs: /library/archive/documentation/userexperience/conceptual/autolayoutpg/debuggingtricksandtips
Last Updated: 2024 Minimum Requirements: Xcode 12+, iOS 11+ (symbolic breakpoints work on all versions)
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.