Xcode

--- name: Xcode description: Avoid common Xcode mistakes — signing issues, build settings traps, and cache corruption fixes. metadata: {"clawdbot":{"emoji":"🔨","requires":{"bins":["xcodebuild"]},"os":["darwin"]}} ---

Signing Issues

• "Automatic" signing still needs team selected — set in Signing & Capabilities
• Provisioning profile mismatch — bundle ID must match exactly, including case
• "No signing certificate" — open Keychain, check certificate is valid and not expired
• Device not registered — add UDID in developer portal, regenerate profile
• CI/CD needs manual signing — automatic doesn't work in headless builds

Derived Data Corruption

• Random build failures after Xcode update — delete ~/Library/Developer/Xcode/DerivedData
• "Module not found" but it exists — clean Derived Data, restart Xcode
• Stale cache symptoms — builds work, then fail, then work again
• xcodebuild clean not enough — sometimes must delete DerivedData manually

Build Settings Hierarchy

• Project → Target → xcconfig → command line — later overrides earlier
• $(inherited) to append not replace — forgetting it removes parent settings
• SWIFT_ACTIVE_COMPILATION_CONDITIONS for Swift flags — not OTHER_SWIFT_FLAGS
• GCC_PREPROCESSOR_DEFINITIONS for Obj-C — add to existing, don't replace

Archive vs Build

• Archive uses Release config by default — build uses Debug
• "Works in simulator, fails in archive" — check Release build settings
• Archive requires valid signing — build doesn't for simulator
• SKIP_INSTALL = YES for frameworks — or archive includes them incorrectly

Capabilities and Entitlements

• Capability in Xcode must match entitlements file — out of sync causes crashes
• Push notifications need both — App ID capability AND provisioning profile
• Associated domains needs apple-app-site-association file — hosted on your server
• Keychain sharing needs explicit group — default is just your app

Dependencies

• SPM and CocoaPods can conflict — watch for duplicate symbols
• Pod update vs install — install uses Podfile.lock, update ignores it
• "Framework not found" — check Framework Search Paths, embed vs link
• SPM package resolution fails — delete Package.resolved, reset package caches

Common Fixes

• Build fails with no clear error — check Report Navigator for details
• Simulator stuck — xcrun simctl shutdown all, then xcrun simctl erase all
• Indexing stuck — delete Index folder in DerivedData
• Autocomplete broken — restart Xcode, if persists delete DerivedData

CLI Builds

• xcodebuild -showBuildSettings to debug — see resolved values
• -allowProvisioningUpdates for CI with auto-signing — needs keychain access
• -destination must be exact — platform=iOS Simulator,name=iPhone 15
• xcrun altool deprecated — use xcrun notarytool for notarization