Introduction

An app that runs in simulator but fails to launch on a physical device usually indicates signing, deployment, or runtime environment mismatch. The fastest way to debug is to separate build-time errors from startup crashes. A repeatable checklist prevents random trial-and-error fixes.

Step 1: Confirm Build and Signing Status

For iOS, verify signing identity, provisioning profile, and bundle identifier alignment. For Android, verify keystore, application id, and debug authorization.

iOS checks in Xcode:

• valid team selected
• device listed in signing profile
• no expired profile or certificate

Android checks in Gradle:

• correct debug or release signing config
• matching package name and manifest entries

Step 2: Validate Device Connection and Trust

Physical connection issues can mimic launch failures.

iOS:

• trust host computer on device
• keep developer mode enabled

Android:

• enable USB debugging
• accept host RSA fingerprint

Useful command:

adb devices

If device is unauthorized or missing, app launch will fail before runtime.

Step 3: Inspect Runtime Logs

Always collect logs from actual launch attempt.

Android:

adb logcat

iOS:

• Xcode device console
• macOS Console app for connected device

Look for first fatal exception rather than later cascading messages.

Step 4: Check Runtime Dependencies

Common launch blockers:

• missing native libraries for target architecture
• unsupported API calls on old OS versions
• required permissions not declared
• invalid startup configuration file

For Android, verify ABI compatibility in build outputs. For iOS, verify framework embedding and minimum deployment target.

Step 5: Clean Install and Rebuild

Stale installs can cause launch mismatch.

Android:

adb uninstall com.example.app
./gradlew installDebug

iOS:

• delete app from device
• clean build folder
• rebuild and run

Fresh deployment removes cached artifacts and outdated signatures.

Step 6: Isolate Startup Code Path

If app installs but crashes instantly, minimize startup path.

• disable nonessential initializers
• test with empty home screen
• re-enable modules incrementally

This quickly identifies failing subsystem such as network bootstrap, database migration, or configuration loader.

Automation for Team Stability

Add a smoke test in CI that builds and deploys to at least one real device farm target. Catching launch regressions early is cheaper than post-release emergency fixes.

Also keep a standard incident template that records OS version, app build, connection method, and first fatal log line.

Platform-Specific Startup Checks

Android:

• verify required permissions in manifest
• confirm minimum SDK is compatible with device
• check ProGuard or R8 rules for startup classes

iOS:

• verify Info.plist keys required by startup modules
• confirm embedded frameworks are signed correctly
• ensure deployment target is not above device OS

Minimal Reproduction Build

Create a tiny build variant that disables optional SDKs and background services. If minimal build launches, re-enable modules one by one to isolate failure quickly. This method is faster than reading thousands of log lines without narrowing scope.

Crash Symbolication Workflow

For release-like builds, symbolicate crash logs so stack traces map to source lines. Unsymbolicated traces hide root causes and slow incident response. Keep dSYM or mapping files accessible in CI artifacts for each build version.

Common Pitfalls

• Focusing on last log message instead of first fatal exception.
• Assuming simulator behavior guarantees device launch success.
• Ignoring signing and trust prompts on physical devices.
• Testing only one OS version while production supports many.
• Keeping stale app installs during repeated troubleshooting.

Summary

• Separate signing, deployment, and runtime failure categories first.
• Verify physical device connectivity and trust state.
• Use platform logs to locate first fatal cause.
• Reinstall cleanly to remove stale artifacts.
• Narrow startup code path to isolate crashing module quickly.