Diagnosing Startup Crashes Caused by App Definition Mismatches in Titanium SDK

The Problem: Immediate Runtime Termination

A Titanium SDK application that crashes immediately upon launch—before any JavaScript code executes—usually indicates a failure in the native boot sequence. This is typically caused by a discrepancy between the titanium.app definition file and the underlying native platform requirements (Android Manifest or iOS Info.plist).

When the OS attempts to initialize the app, it checks for a valid bundle identifier, required permissions, and resource mappings. If the Titanium SDK provides a definition that contradicts the native project state or misses a mandatory key, the OS terminates the process to prevent security or stability risks.

Diagnostic Quick-Reference

Symptom	Likely Cause	Primary Diagnostic Tool
Crash during splash screen	App-ID mismatch or missing Bundle ID	Device System Logs
Crash after permission request	Undefined permission in titanium.app	Logcat / Console.app
Crash only after a project rename	Stale build artifacts in /build folder	File System Check
Crash on specific OS version	Missing platform-specific manifest key	SDK Version Log

Step-by-Step Resolution Path

1. Verify App-ID Consistency

The app-id defined in your project settings must exactly match the bundle identifier expected by the native platform. A mismatch often occurs after migrating projects or changing the app name.

• Open the titanium.app file in your project root.
• Ensure the app-id follows the reverse-DNS notation (e.g., com.company.appname).
• Check that no trailing spaces or hidden characters exist in the string.

2. Audit Required Permissions

If your app requests a native capability (like Camera or Location) that is not explicitly declared in the app definition, the OS will kill the app the moment the SDK attempts to initialize that module.

Check the permissions section of your configuration. For example, an Android app requiring camera access must have the corresponding entry in the SDK project settings to ensure it is injected into the AndroidManifest.xml during the build process.

3. Clear Stale Build Artifacts

Titanium SDK caches build artifacts to speed up deployment. However, if the titanium.app file is updated but the build folder retains an older version of the native project, the deployed app will use an outdated definition.

Run the following command from your terminal in the project root to force a clean state:

# Run from the project root directory
# Requires Titanium CLI installed and in PATH
titanium build -c

Risk: This removes all compiled binaries, increasing the time for the next build. Do not delete the entire SDK installation folder, only the project-specific build directory.

4. Analyze System Logs for Root Cause

Since the crash happens before the JavaScript engine starts, Ti.print() statements are useless. You must use native logging tools.

• Android: Use adb logcat. Search for FATAL EXCEPTION or ClassNotFoundException.
• iOS: Use Console.app on macOS. Filter by the process name and look for Termination Reason: Namespace SIGNAL or missing Info.plist keys.

Decision Matrix: When to Escalate

If the following conditions are met, the issue is likely a bug in the SDK version rather than a configuration error:

• The app-id is verified and identical across all settings.
• A titanium build -c was performed and the crash persists.
• The crash only occurs on a specific OS update (e.g., moving from Android 13 to 14) while using an older SDK version.

Verification of Fix

To confirm the resolution, perform a fresh deployment to a clean emulator or device. The app is considered stable if it reaches the first app.js execution point. You can verify this by placing a Ti.alert('Boot Successful'); as the first line of your main JavaScript file.

Rollback Procedure

If changes to the titanium.app file cause new regressions:

1. Revert the titanium.app file to the last known working version using your version control system (e.g., git checkout titanium.app).
2. Run titanium build -c to ensure the reverted configuration is correctly propagated to the native binaries.