Nine Xcode Configuration Errors to Catch Before Archive
The nine deterministic checks currently implemented by Xcode Doctor, how they derive evidence from project files, and what they deliberately cannot verify.
An Xcode archive can fail even when the application compiles and runs locally. Multi-target projects distribute their configuration across project.pbxproj, build settings, Info.plist files, and entitlements. A value that is valid in isolation can still contradict the containing app, an extension, or another build configuration.
Xcode Doctor is a native macOS project that parses those local files and runs nine deterministic checks. The current scanner is read-only. It produces evidence and guidance; its automated fix engine is still in development.
This is the exact current check catalog—not a list of planned features.
How the scan is structured
ProjectParser resolves the selected Xcode project, reads its project object graph, finds PBXNativeTarget entries, resolves build configurations, and builds a ProjectContext. Each target record can include its product type, bundle identifier, development team, signing style, deployment target, Info.plist URL, entitlements URL, and linked frameworks.
Each diagnostic conforms to a small protocol:
protocol DoctorCheck {
var checkID: String { get }
var title: String { get }
func run(in context: ProjectContext) throws -> DoctorIssue?
}
The scanner runs all nine checks, reports progress, continues when an individual check throws, and sorts the resulting issues by severity. Evidence records point back to build settings, plist keys, entitlement keys, or framework references.
1. Watch companion mismatch
Check ID: watch.companion.mismatch
A Watch app declares the bundle identifier of its containing iOS companion through WKCompanionAppBundleIdentifier. The check compares that value with the main iOS application's bundle identifier and also reports missing identifiers.
A mismatch can prevent the Watch app from pairing or installing with the intended companion. The evidence should include both the declared companion identifier and the identifier expected from the iOS target.
2. CloudKit container mismatch
Check ID: cloudkit.container.mismatch
CloudKit configuration is spread across entitlements and target configuration. The diagnostic reads the entitlements dictionary and examines the configured iCloud container identifiers. It reports absent or inconsistent container values rather than contacting the Apple Developer Portal.
That boundary matters: a local file analyzer can verify internal project consistency, but it cannot claim that a container exists or is enabled in Apple's remote account state.
3. Widget bundle identifier
Check ID: widget.bundle.identifier.invalid
A WidgetKit extension should have its own bundle identifier, namespaced beneath the containing app. The diagnostic finds widget-extension targets and flags identifiers that are identical to the app identifier or do not begin with the app identifier plus a suffix.
For an app using com.example.product, a widget identifier such as com.example.product.widget expresses the containment relationship. com.example.widget does not.
4. Missing WidgetKit framework
Check ID: widgetkit.framework.missing
The parser resolves linked frameworks from the target's framework build phase. Each widget target is checked for a WidgetKit framework reference. The report includes the target and its current framework list.
This catches a project-graph inconsistency. It does not execute or render the widget, so a passing result is not proof that the widget's timeline or SwiftUI view is correct.
5. Signing inconsistency
Check ID: signing.inconsistent
Related targets should not quietly disagree about the development team or signing style. This check compares locally declared signing settings across targets and reports contradictions that can surface during archive.
It does not validate certificate expiration, inspect an Apple Developer account, or guarantee that a matching provisioning profile exists. Those are different operations requiring different evidence.
6. Bundle identifier collision
Check ID: bundle.identifier.collision
Every installable target needs an appropriate, distinct identity. The diagnostic groups targets by bundle identifier and reports collisions where multiple targets claim the same value.
Collisions are easy to introduce after duplicating a target or copying build configurations. They can produce signing, installation, or extension-discovery failures late in the release process.
7. App Group consistency
Check ID: app.group.consistency
Apps and extensions use App Group entitlements to share containers. The check reads target entitlements and compares the declared groups across related targets. Evidence identifies which target declares which group.
Different groups can be intentional, so the diagnostic must preserve context. Its job is to expose the difference and its likely impact, not to overwrite all targets with one value.
8. Deployment-target mismatch
Check ID: deployment.target.mismatch
Extensions, widgets, and Watch targets must have deployment targets compatible with the containing application and the APIs they use. The check collects target versions and reports incompatible relationships, including an extension configured below the app's deployment target.
Changing a deployment target can introduce API-availability consequences. Xcode Doctor therefore describes the mismatch and a suggested correction but does not currently mutate the project.
9. Entitlement without corresponding capability
Check ID: entitlement.without.capability
Certain entitlement keys normally accompany an enabled Xcode capability. The diagnostic maps recognized entitlement keys to their expected capability and reports their presence with evidence from the entitlements file.
This is intentionally a local presence check. It cannot verify remote App ID configuration, and the implementation says so in its diagnostic text. That is the difference between evidence-based static analysis and an unsupported claim about Apple account state.
Why evidence matters more than a red badge
A useful configuration tool should answer four questions:
- Where did the value come from?
- What value was found?
- What relationship or invariant was expected?
- What is the consequence of changing it?
Xcode Doctor's issue model records sources, current and expected values, affected targets, severity, impact, and proposed steps. That structure makes a result reviewable by a developer instead of presenting an unexplained pass/fail score.
What the current tool does not claim
The repository currently does not prove App Store acceptance. It does not contact App Store Connect or the Developer Portal, manage certificates, run CI, or modify Swift source. Scanning is local and read-only, and automated changes remain a future milestone.
Those boundaries make the results more trustworthy. Static analysis should be precise about what can be inferred from files and what requires a build, account access, device test, or submission.
Run or inspect Xcode Doctor
The repository includes the parser, all nine check implementations, issue model, MIT license, and a verified macOS CI build.