Troubleshooting

Build Failures

Mobile builds on Emergent can fail for a variety of reasons. Most are fixable by reviewing credentials, dependencies, or build logs.

Info

Emergent manages your Expo/EAS account entirely, you never need to create an Expo account, install

eas-cli

, purchase EAS credits, or modify

eas.json

. All native builds (APK/AAB/IPA) are triggered from the Publish panel and are built from the last published code. If you've made a fix in the agent, re-publish first, then trigger a new build.

Common causes and fixes:

Expired or missing push credentials: Emergent manages signing, but push-notification credentials come from you. If your build fails around push credentials, ask the agent to set up Emergent-managed push notifications and share your keys with it (the APNs
```
.p8
```
push key for iOS, the Firebase service-account key for Android), then re-publish and build again. If it still fails, send the build logs to the agent or contact support.
Pre-existing Play Store app (keystore mismatch): if an app with the same package name was already listed on the Play Store, the AAB upload fails because the signing keys don't match. Contact support@emergent.sh - they'll either align Emergent's signing to your existing keystore, or give you the key material (SHA fingerprints and a .pem) to apply in the Play Console as an upload-key reset (2-3 business days on Google's side). See Publishing to the stores for details.
Native dependency conflicts: If your app uses a library that requires specific native modules or has incompatible peer dependencies, the build may fail during dependency resolution. Review the build logs for
```
npm
```
or
```
yarn
```
errors and ask the agent to update or remove the conflicting package.
Incorrect
app.json
configuration: Typos in bundle identifiers or version codes will cause validation errors. Bundle IDs are seeded into
```
app.json
```
at setup (
```
com.emergent.<words>.<suffix>
```
) and are editable in the pre-populated first-build form. Do not modify
```
eas.json
```
.
Backend changes not yet published: Native builds use the last published code. If you have made backend changes since your last publish, re-publish first, then trigger the new build from the Publish panel.

Read the build logs

Always expand the full build log in the Emergent Publish panel. The error is usually near the end and tells you exactly which step failed.

Submission Rejected

Apple and Google both review submissions before your app goes live. Common rejection reasons include:

Reason	Platform	Fix
Missing privacy policy or terms of service	Both	Add a publicly accessible link in your app's store listing and in-app settings.
Sign in with Apple not implemented	iOS	If you offer any third-party sign-in (Google, Facebook), Apple requires you also offer Sign in with Apple. Add it or remove other social logins.
App crashes on launch	Both	Test on a physical device before submission. Production builds may behave differently from preview, always test a production `.ipa` or `.aab` .
Incomplete or misleading screenshots	Both	Use real app screenshots that accurately represent functionality. Avoid mockups or marketing graphics that don't match the actual UI.
Incorrect age rating	Both	Ensure your app's content rating matches what reviewers see. If your app allows user-generated content, declare it and implement moderation.
Bundle ID or package name mismatch	Both	The identifier in your build must exactly match what you registered in App Store Connect or Google Play Console. Check `app.json` → `ios.bundleIdentifier` and `android.package` .

A common iOS rejection occurs when Sign in with Apple is configured with the wrong audience (client ID). See the dedicated section below for the fix, this is a backend-only configuration change and does not require a new build number or resubmission.

If your app is rejected, the store will provide specific feedback. Address each point and work with the Emergent agent to resolve the underlying issue.

Updates Not Appearing

You've made a change but users aren't seeing the new version.

Why this happens and what to do:

OTA updates are not enabled: Emergent does not currently deliver over-the-air updates. Getting changes to your users always means re-publishing and then building.
Backend-only changes: changes to your backend (API logic, database) ship when you re-publish - no new build or store submission is needed, because the backend runs on Emergent's servers.
App changes (JS or native): any change to the app itself - JavaScript included - requires a re-publish followed by a new native build from the Publish panel, and a store submission for that new build.

Re-publish your latest changes

In the Emergent platform, use the Re-publish button to publish your latest code. Native builds always use the last published version: fix first, re-publish, then rebuild.

Trigger a new native build

Start a new build from the Publish panel for the target platform. OTA updates are not enabled, so a new build is required for any app change.

Submit the new build to the stores

For Android, upload the new

.aab

to the Play Console. For iOS, the TestFlight upload is handled for you; promote the build in App Store Connect.

Icons Show as Boxes on Android

Note

This issue affects only older Emergent-generated apps. The app template has since been fixed, so newly created projects should not encounter it.

When testing on Android, vector icons from libraries like

@expo/vector-icons

react-native-vector-icons

may render as empty boxes (sometimes called "tofu") in certain builds.

Cause: The older app template did not bundle every icon font correctly for Android. The iOS build was unaffected, which is why the issue is Android-specific.

Fix:

Use a production build for testing

Trigger a new native build from the Emergent Publish panel. Standalone builds include all icon fonts your app declares.

Migrate to SVG assets (recommended long-term fix)

For a durable solution, ask the agent to replace vector icon libraries with SVG assets rendered via

react-native-svg

. SVG migration is the recommended long-term approach, as it avoids font-bundling issues entirely and scales well across screen densities.

Re-publish before rebuilding

Remember: native builds use the last published code. After the agent makes icon changes, use Re-publish to publish, then trigger a new build from the Publish panel.

Tip

Once you have a properly built standalone

.apk

.aab

from the updated template, icons will render correctly.

Symptom: Your iOS app is rejected with a message like "Sign in with Apple does not work" or "Invalid client configuration," even though authentication works fine in testing.

Root cause: Sign in with Apple validates the audience (

aud

) claim in the ID token. If your backend or auth provider is configured to use the wrong client ID, often the Services ID instead of the bundle identifier, Apple's review team will see a validation error.

Important: This is a backend-only configuration fix. It applies to the build already in review. Bumping the build number and submitting a new binary does not resolve this issue and is not necessary.

How to fix:

Identify which identifier you're using

Check your backend's Apple auth configuration or your Firebase/Auth0/Supabase settings. Look for the field labeled "Client ID," "Services ID," or "Audience."

Use the bundle ID, not the Services ID

For native iOS apps, the

aud

claim in the ID token must match your app's bundle identifier (e.g.,

com.emergent.yourapp.xyz

), not the Services ID you created in the Apple Developer portal.

Ask the agent to update your backend auth config

Describe the misconfiguration to the Emergent agent. The fix is made in the backend code/configuration, for example, updating the audience field in your Firebase, Auth0, Supabase, or custom backend Apple connection settings.

Re-publish the backend fix

Use Re-publish to publish the corrected backend configuration. Because this is a backend-only change, the fix takes effect without a new native build or store resubmission, Apple can re-review the same binary once your backend is corrected.

Warning

Do not share the same Services ID across web and native. Use the bundle ID for iOS native apps and a separate Services ID for your web client if you have a browser-based flow.

Quick Reference

An at-a-glance checklist for mobile publishing and troubleshooting.

Pre-Submission Checklist

Bundle ID (iOS) and package name (Android) match your store registrations
App version and build number - handled automatically by Emergent, nothing to set
App icon and splash screen assets present and correctly sized
Privacy policy and terms of service URLs live and accessible
Sign in with Apple implemented if you offer any third-party sign-in (iOS only)
All required permissions declared and justified in store listing
Latest changes re-published before triggering a native build
Push credentials shared with the agent, if your app uses push notifications (ask the agent to set up Emergent-managed push before you build)
App tested on a production build - via TestFlight (iOS) or by downloading the APK (Android)

Emergent Mobile Build Workflow

Task	How to do it on Emergent
Trigger a native iOS or Android build	Publish panel → select platform
Ship a backend-only update	Re-publish in the Publish panel
Ship an app update (JS or native)	Re-publish, then trigger a new build from the Publish panel
Submit to App Store	Emergent handles TestFlight upload; App Store Connect API key is auto-managed
Submit to Play Store	Emergent handles AAB submission; register your package name in Play Console
View build logs	Publish panel → build history
Contact support	support@emergent.sh or in-app live chat (Emmy)

Note

You do not run

eas build

eas submit

eas update

eas credentials

, or any

eas-cli

commands. All of these are handled by Emergent. Do not modify

eas.json