Diagnosing Silent Startup Crashes in Titanium SDK Applications

The Problem: The Silent Crash

A common failure point in Titanium SDK development is the "silent crash," where an application terminates immediately upon launch without producing any JavaScript errors in the Titanium console. Because the failure occurs during the native initialization phase—before the JavaScript engine is fully operational—standard console.log debugging is ineffective.

The root cause is typically a mismatch between the JavaScript-level module requests and the actual native binaries linked into the application package. When the native bridge attempts to instantiate a module that is missing or incompatible, the operating system terminates the process. The diagnostic workflow below applies to Titanium SDK 10.x/11.x/12.x; note that Axway sunset the Titanium SDK in 2024, so current development typically relies on the community-maintained fork (titanium_mobile). Toolchain compatibility details change over time—verify against the release notes for your SDK version.

Diagnostic Matrix

Use this table to identify the likely cause based on the native log output found in Xcode (iOS) or Android Studio/Logcat (Android).

Native Log Error	Likely Cause	Primary Suspect
java.lang.UnsatisfiedLinkError	Missing native library (.so file)	Incorrect module version or failed build link
Symbol not found / dyld: Symbol not found	API mismatch	SDK version mismatch with native toolchain
ClassNotFoundException	Missing Java class	Module not declared in project settings

Step-by-Step Diagnostic Workflow

Follow these checks in order. Do not move to the next step until the current check is verified.

1. Capture Native Logs

Since the Titanium console is empty, you must use the platform-specific logging tool to see the crash reason.

• Android: Run adb logcat *:E via the terminal while launching the app. Look for FATAL EXCEPTION.
• iOS: Open the project in Xcode, run the app on a physical device or simulator, and monitor the All Output console at the bottom of the IDE.

2. Verify Module Linking

Check your tiapp.xml file in the <modules> section. Ensure that every native module required by your code is explicitly listed. If you recently added a module via a package manager or manual installation, verify that the native binaries are present in the build folder.

3. Validate Toolchain Alignment

Titanium SDK releases are tightly coupled with specific versions of Xcode and the Android SDK Build-Tools. Verify that your installed environment matches the SDK requirements:

• Android: Check build.gradle or project settings to ensure the compileSdkVersion and buildToolsVersion match the SDK documentation.
• iOS: Ensure the Xcode version is compatible with the SDK's target iOS deployment version.

Resolution Paths

Fix A: Force Native Re-link

If the logs indicate a UnsatisfiedLinkError or a missing symbol, the build cache may be corrupted or outdated.

1. Perform a Clean Project (In Studio: Project > Clean).
2. Manually delete the build folder in your project directory.
3. Rebuild the application. This forces the SDK to re-evaluate the tiapp.xml and re-link all native binaries.

Risk: If you have manually modified native files inside the build folder (rather than using a proper module structure), these changes will be lost.

Fix B: Toolchain Synchronization

If the logs show Symbol not found, your native compiler is likely using a different API version than what the Titanium SDK expects.

1. Update (or downgrade) the Android SDK Build-Tools to the specific version recommended for your Titanium SDK release.
2. For iOS, ensure the correct Xcode Command Line Tools are selected in Xcode > Settings > Locations.
3. Rebuild the project.

Risk: Updating toolchains can break other projects on the same machine that rely on older SDK versions.

Verification of Fix

To confirm the application has successfully passed the native initialization phase, place a log statement at the absolute top of your app.js file:

console.log("NATIVE_INIT_SUCCESS: App has reached JavaScript entry point");

Run the app via the Titanium CLI. If this message appears in the console, the native bridge is functioning and the startup crash is resolved.

Escalation Criteria

If the following conditions persist, the issue is likely a bug in the native module itself rather than a configuration error:

• The crash occurs even after a full clean and toolchain alignment.
• The native log shows a Segmentation Fault or NullPointerException inside a third-party module's internal class.
• The crash only occurs on a specific OS version (e.g., Android 14) while working on others.