Troubleshooting

Build Errors

SwiftUI Preview Issues

SwiftUI previews often fail when React Native is in the project due to build complexity.

Clear SwiftUI preview cache

Run this command to clear corrupted preview cache:

xcrun simctl --set previews delete all

Then restart Xcode and try the preview again.

Prebuild without React Native

For faster development of native-only extensions, use the blank template:

npx expo prebuild --template ./node_modules/@bacons/apple-targets/prebuild-blank.tgz --clean

This is for development only. Never use this template for production builds—it removes React Native entirely.

This is useful when:

Building widgets that don’t use React Native
Working on SwiftUI previews
Iterating on native UI quickly

Switch back to normal prebuild for production:

npx expo prebuild --clean

Disable SwiftUI previews

If previews continue to cause issues, comment them out temporarily:

// #Preview {
//     MyWidget()
// }

You can still build and test on device/simulator without previews.

If your widget builds successfully but doesn’t appear on the home screen:

Use iOS 18+

On iOS 18, you can transform the app icon into a widget:

Long-press your app icon on the home screen
Tap “Edit Home Screen”
Select widget display options
Choose your widget configuration

This is easier than the traditional widget gallery flow.

Check widget gallery

Verify widget is installed

CocoaPods Errors

CocoaPods version too old

This plugin requires CocoaPods 1.16.2 or later:

# Check version
pod --version

# Update if needed
gem install cocoapods

# Or with Homebrew
brew upgrade cocoapods

Also ensure Ruby 3.2.0+:

ruby --version

pods.rb not being evaluated

Ensure:

The file is named exactly pods.rb (case-sensitive)
It’s in the repository root (not in /ios or /targets)
The target name matches your directory name exactly
You’ve run npx expo prebuild --clean after creating it

Test by adding a debug line:

puts "pods.rb is being evaluated!"

You should see this during pod install.

Pod install fails

Try these steps in order:

# Clear Pods cache
rm -rf ios/Pods ios/Podfile.lock

# Clear CocoaPods cache
pod cache clean --all

# Prebuild fresh
npx expo prebuild --clean

# Install
cd ios && pod install

If that doesn’t work, check the Podfile for syntax errors:

cat ios/Podfile

Compilation Errors

Swift compiler errors

Swift compiler errors in widgets are often caused by React Native’s uncompiled sources.Solution 1: Use the blank template (dev only)

npx expo prebuild --template ./node_modules/@bacons/apple-targets/prebuild-blank.tgz --clean

Solution 2: Increase build memoryIn Xcode:

Product > Scheme > Edit Scheme
Build > Build Options
Enable “Debug Information Format” > “DWARF”
Disable “Enable Bitcode”

Cannot find type in scope

If Swift can’t find types from _shared files:

Verify the file is in _shared directory
Run npx expo prebuild --clean
Check file target membership in Xcode:
- Select the file
- Open File Inspector (⌥⌘1)
- Ensure both targets are checked

Duplicate symbol errors

Multiple targets compiling the same file:

duplicate symbol '_OBJC_CLASS_$_MyClass'

This happens when:

A file is in both a target directory AND _shared
Multiple _shared directories define the same type

Solution: Move the file to only one location, typically _shared if it needs to be in multiple targets.

Runtime Errors

App Clip Crashes

Crash on launch from TestFlight

You may need this React Native patch for App Clips launched from TestFlight.Workaround: Add App Clip experiences in App Store Connect first. The App Clip will launch correctly when invoked through an experience.

expo-updates crash in App Clip

App Clips should NOT include expo-updates:

// package.json
{
  "dependencies": {
    // Remove expo-updates for App Clip projects
    // "expo-updates": "..."
  }
}

The over-the-air update mechanism conflicts with App Clip constraints.

Bundle not found error

If React Native can’t find the JS bundle in your App Clip:

Verify exportJs: true in target config
Ensure you’re building in Release mode
Check the bundle exists:

ls -la ios/build/Build/Products/Release-iphonesimulator/YourApp.app/*.appex/main.jsbundle

Verify your pods.rb includes React Native dependencies

Widget shows old data

Force reload the widget from your app:

import { ExtensionStorage } from '@bacons/apple-targets';

// Reload all widgets
ExtensionStorage.reloadWidget();

// Or reload a specific widget
ExtensionStorage.reloadWidget('com.yourapp.widget');

Shared data not syncing

Check App Groups configuration:

Verify the App Group ID matches in both targets:
- Main app: app.json > ios.entitlements
- Widget: expo-target.config.js > entitlements
Use the exact same App Group identifier:

// Main app (app.json)
{
  "ios": {
    "entitlements": {
      "com.apple.security.application-groups": ["group.com.yourapp.data"]
    }
  }
}

// Widget (expo-target.config.js)
module.exports = {
  type: "widget",
  entitlements: {
    "com.apple.security.application-groups": ["group.com.yourapp.data"]
  }
};

Check that both targets are signed with the same team

Code Signing Issues

Provisioning profile errors

For first-time setup:

Run npx expo prebuild --clean
Open Xcode: xed ios
Select each target
Go to “Signing & Capabilities”
Select your team for each target
Let Xcode create provisioning profiles

This ensures the initial signing is correct before EAS Build.

App Clip signing issues

App Clip codesigning is complex. For EAS Build:

Ensure all targets use the same Apple Team ID
Create provisioning profiles for each target in Apple Developer Portal
App Clips need parent application identifier entitlement:

<!-- Auto-generated for App Clips -->
<key>com.apple.developer.parent-application-identifiers</key>
<array>
    <string>$(AppIdentifierPrefix)com.yourapp.bundle</string>
</array>

This is added automatically by the plugin.

Mismatched bundle identifiers

Ensure consistent bundle IDs:

// Main app (app.json)
{
  "ios": {
    "bundleIdentifier": "com.yourcompany.yourapp"
  }
}

// Extension (expo-target.config.js)
module.exports = {
  type: "widget",
  bundleIdentifier: ".widget",  // Dot-prefix appends to main bundle ID
};
// Results in: com.yourcompany.yourapp.widget

Development Workflow Issues

Changes not appearing after edit

Depends on what you changed:Swift/native code changes:

Just rebuild in Xcode (⌘B)
No prebuild needed

Target config changes:

Run npx expo prebuild --clean
Examples: changing type, adding frameworks, updating entitlements

Adding/removing files in _shared:

Run npx expo prebuild --clean
Content changes don’t need prebuild

Info.plist changes:

Just rebuild in Xcode
Info.plist is not managed by prebuild

Metro connection failing in extension

Extensions with React Native need to connect to Metro during development:

Ensure Metro is running: npx expo start
Check Info.plist has App Transport Security exception:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

Verify device and dev machine are on the same network
Try connecting by IP address if localhost fails

Hot reload not working

Hot reload doesn’t work in extensions. You must:

Save your changes
Rebuild in Xcode (⌘B)
Reinstall the app

This is a React Native limitation for extensions.

EAS Build Issues

Build succeeds locally but fails on EAS

Common causes:

Credentials not configured: Add provisioning profiles for all targets
CocoaPods version mismatch: Pin Ruby version in eas.json
Missing secrets: Environment variables not set in EAS

Check the build logs for specific errors.

Target not included in IPA

Verify the target is embedded in the main app:

In Xcode, select the main app target
Go to “General” tab
Check “Frameworks, Libraries, and Embedded Content”
Your extension should be listed as “Embedded”

If missing, run npx expo prebuild --clean.

Advanced Debugging

Enable verbose prebuild logging

DEBUG=expo:* npx expo prebuild --clean

This shows detailed logs about what the plugin is doing.

Inspect Xcode project file

The plugin modifies the .pbxproj file. To see raw changes:

git diff ios/YourApp.xcodeproj/project.pbxproj

Useful for debugging why targets aren’t configured correctly.

Test target in isolation

Build just one target to isolate issues:

cd ios
xcodebuild -workspace YourApp.xcworkspace \
  -scheme your-target \
  -sdk iphonesimulator \
  -configuration Debug \
  build

Replace your-target with your extension’s target name.

Getting Help

If you’re still stuck:

Check the example apps in the repository for working configurations
Search GitHub issues: github.com/evanbacon/expo-apple-targets/issues
Ask on Expo Forums: forums.expo.dev
File a bug report with:
- Minimal reproduction
- Full error logs
- Xcode version
- Expo SDK version

When asking for help, always include:

Your target type
Full error message
Output of npx expo-env-info
Relevant config files (expo-target.config.js, app.json)

Get Started

Core Concepts

Guides

Advanced

Build Errors

SwiftUI Preview Issues

Widget Not Showing on Home Screen

CocoaPods Errors

Compilation Errors

Runtime Errors

App Clip Crashes

Widget Not Updating

Code Signing Issues

Development Workflow Issues

EAS Build Issues

Advanced Debugging

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Build Errors

​SwiftUI Preview Issues

​Widget Not Showing on Home Screen

​CocoaPods Errors

​Compilation Errors

​Runtime Errors

​App Clip Crashes

​Widget Not Updating

​Code Signing Issues

​Development Workflow Issues

​EAS Build Issues

​Advanced Debugging

​Getting Help

​Related Documentation

Build docs developers (and LLMs) love

Build Errors

SwiftUI Preview Issues

Widget Not Showing on Home Screen

CocoaPods Errors

Compilation Errors

Runtime Errors

App Clip Crashes

Widget Not Updating

Code Signing Issues

Development Workflow Issues

EAS Build Issues

Advanced Debugging

Getting Help

Related Documentation