Introduction

The Missing CFBundleIconName warning usually shows up when an archive is validated for App Store distribution, even though the app seems to run normally on a simulator or test device. Xcode 9 and iOS 11 made icon metadata validation stricter, so projects with older icon setup often started failing only at release time.

In most cases the problem is not that the icon files are missing. The real problem is that the target, asset catalog, and generated Info.plist metadata do not agree on which app icon set is the primary one.

Why Xcode Reports This Key

CFBundleIconName identifies the primary app icon resource. In modern projects you usually do not type that key into Info.plist yourself. Xcode generates the value from the App Icon asset catalog setting for the target.

That means the warning appears when one of these is true:

• the target is not pointing at a valid App Icon set
• the asset catalog exists but the app icon set was renamed or deleted
• the project still mixes legacy icon keys with asset-catalog-based configuration
• an old custom Info.plist overrides the generated values

A useful first check is to inspect the build settings that control asset catalog compilation:

xcodebuild -scheme MyApp -showBuildSettings | rg 'ASSETCATALOG|INFOPLIST'

If the app icon name is missing from the relevant settings, Xcode has no clear source for the generated bundle icon metadata.

Fix the Target Configuration First

Open the target in Xcode and verify the App Icons and Launch Images section under General. The App Icons Source field should point to the real icon set, commonly named AppIcon.

Then open Assets.xcassets and confirm that the icon set exists and contains the required slots for the platforms you ship. A common failure mode is renaming AppIcon to something else while leaving the target pointing at the old name.

You can also inspect the built app directly after an archive:

plutil -p 'build/Release-iphoneos/MyApp.app/Info.plist' | rg 'CFBundleIcons|CFBundleIconName'

If the archive does not contain CFBundleIconName, the build output confirms the problem is in project configuration, not in App Store Connect.

When Manual Info.plist Edits Are Appropriate

For most current Xcode projects, manual plist edits are a fallback, not the preferred fix. Still, if you maintain an older project or use custom build tooling, adding the primary icon entry explicitly can be a valid repair.

1<key>CFBundleIcons</key>
2<dict>
3  <key>CFBundlePrimaryIcon</key>
4  <dict>
5    <key>CFBundleIconName</key>
6    <string>AppIcon</string>
7  </dict>
8</dict>

Use this only when it matches the actual asset catalog name. If the icon set is called AppIcon-Prod, writing AppIcon into the plist only creates a different mismatch.

Clean Build Artifacts and Re-Archive

After changing icon configuration, remove stale build products. Xcode caches asset catalog output aggressively enough that a configuration bug can appear to survive even after the project is fixed.

A practical sequence is:

1. clean the build folder in Xcode
2. delete the previous archive
3. build a new archive
4. inspect the archived Info.plist
5. validate again

This matters because simulator runs do not prove release metadata is correct. Archive validation is the step that exercises the full packaging path.

Common Pitfalls

• Editing Info.plist first instead of fixing the target’s App Icons Source value.
• Keeping old icon arrays from pre-asset-catalog projects while also expecting Xcode to generate icon metadata.
• Renaming the icon set in Assets.xcassets and forgetting to update the target.
• Checking only local runs and skipping inspection of the archived app bundle.
• Assuming every icon warning means files are missing, when the real issue is inconsistent naming.

Summary

• 'CFBundleIconName identifies the primary app icon resource for the app bundle.'
• In modern Xcode projects, Xcode usually generates that key from the asset catalog settings.
• The main fix is to make the target, asset catalog, and plist metadata agree on the same icon set name.
• Manual plist entries are a fallback for older or custom build setups.
• Always validate the archived app, not just simulator output.