Fix Android SDK Location Errors in Appcelerator Titanium Builds

When Appcelerator Titanium reports "Failed to locate Android SDK" during a build, the root cause is usually an environment mis‑configuration. This guide walks through a step‑by‑step diagnostic checklist, fixes tied to findings, and escalation paths to get your Android builds running again.

Problem Statement

When running ti build -p android or launching an Android emulator, the Titanium CLI often aborts with:
Error: Failed to locate Android SDK. This blocks both development and CI pipelines.

Recognizable Condition

The CLI immediately prints the error message and exits before any build artifacts are produced. No APK is generated, and the emulator never starts.

Root Causes (Quick Reference)

Cause	Typical Symptoms
ANDROID_HOME unset or wrong	CLI cannot find "platforms" or "platform-tools" directories.
Missing Android platform SDK (e.g., API 30)	Build log shows "platforms;android-30 not found".
Outdated SDK tools or platform‑tools	CLI warns about version mismatch or cannot launch emulator.
Corrupted SDK installation	Directory missing expected subfolders or contains incomplete files.

Ordered Diagnostic Checklist

Verify ANDROID_HOME
Run:
```
echo $ANDROID_HOME   # Linux/macOS
echo %ANDROID_HOME%   # Windows
```
Check that the path points to the SDK root and that the directory contains platforms, platform-tools, and tools subfolders.
Inspect SDK Directory Structure
Navigate to $ANDROID_HOME and list:
```
ls -l platforms
ls -l platform-tools
ls -l tools
```
All three should exist and be readable.
List Installed Platforms
Execute the SDK manager:
```
sdkmanager --list | grep platforms
```
Look for the API level required by your tiapp.xml (e.g., platforms;android-30).
Check Build Tools Version
Run:
```
sdkmanager --list | grep build-tools
```
The Titanium CLI documentation specifies a minimum build‑tools version (e.g., 30.0.3). If absent, install it.
Review Build Log for Additional Clues
Re‑run the build with trace level:
```
ti build -p android --log-level trace
```
Search the output for any mentions of missing directories or permission errors.

Fixes Tied to Findings

Set or Correct ANDROID_HOME
For a fresh install:
```
# Linux/macOS
export ANDROID_HOME=/opt/android-sdk
# Windows (cmd)
set ANDROID_HOME=C:\Android\sdk
```
Add the export to ~/.bashrc or ~/.profile so it persists across sessions.
Install Missing Platform
Example for API 30:
```
sdkmanager "platforms;android-30"
```

Update Tools and Build‑Tools

sdkmanager "platform-tools" "build-tools;30.0.3"

Clean and Rebuild
```
ti clean
ti build -p android
```
Verify Emulator Compatibility
Launch a test AVD:
```
ti emulator -p android --avd MyTestAVD
```

Escalation Criteria

If the error persists after completing the steps above, proceed with:

Collect a full trace log: ti build -p android --log-level trace > build.log.
Check file permissions on $ANDROID_HOME and its subfolders; ensure the user running the build has read/write access.
Consider reinstalling the Android SDK entirely. Backup platforms and build-tools if you have custom configurations.
Submit the trace log, tiapp.xml, and environment variables to Appcelerator support for deeper investigation.

Limitations & Practical Verification

Spaces in ANDROID_HOME can cause parsing errors; if unavoidable, quote the path in scripts.
Using SDK versions older than the minimum required by your Titanium SDK may lead to silent failures; always match the version matrix documented by Appcelerator.
After applying fixes, confirm success by generating an APK:
```
ti build -p android -T apk
```
The command should output a path to build/android/Release/MyApp.apk without error.

Concrete Example

Assume a Mac user reports the error. The user’s ~/.bash_profile contains:

export ANDROID_HOME=/Users/jane/Android/sdk

Running ti build -p android yields the SDK error. Diagnostics reveal that the platforms folder is missing. The user installs API 30:

sdkmanager "platforms;android-30"

Then updates build‑tools:

sdkmanager "build-tools;30.0.3"

After ti clean and rebuild, the APK is produced successfully. The issue was a missing platform SDK, not an environment variable problem.

Conclusion

By systematically validating ANDROID_HOME, inspecting the SDK layout, and ensuring required platform and build‑tools are present, most Titanium Android build failures can be resolved quickly. Persisting issues warrant a trace log and support escalation.

Resolving Android SDK Location Errors in Appcelerator Titanium Builds