Separate Android AI Build Failures from Runtime Failures

Direct answer

A successful Android build answers a narrow question: the selected source and build configuration produced an artifact. It does not prove that the artifact installs on every target, contains every required native library, opens the intended model, initializes a backend, or completes a user task. Troubleshooting is faster when the first failing stage is recorded before any setting changes. Use a stage ledger with build, package inspection, install, process launch, native load, model load, backend initialization, first inference, output validation, and next-request recovery. Assign each failure to the earliest stage supported by evidence; do not label every post-install crash a model error. Start by saving the exact Gradle task, variant, commit, dependency lock, resolved runtime, build output and install source. Compare the artifact that was built with the artifact that was installed; a release bundle, device-targeted split and local debug APK are not interchangeable. Android Studio APK Analyzer can inspect final manifest, DEX, resources and native-library entries. Use it to compare the generated package with the declared build, not to infer that a packaged library will load successfully. If the failure occurs during installation, capture the package-manager result and device ABI; if the application launches and then throws `UnsatisfiedLinkError`, inspect the required library name, ABI directory, dependent native objects, load order and error detail. Android NDK documentation explains that library-not-found messages can also reflect a library that exists but cannot be opened because of dependencies. Preserve the full first exception and native log instead of retrying blindly. If the native runtime opens but model initialization fails, record the exact artifact source, revision, format, byte length, path, parser/runtime revision and initialization stage. Do not infer file integrity from an extension, provider label, successful copy, or file length alone. Cove's current Gemma E2B configuration has no verified SHA-256 value, so the site cannot describe that model hash as verified. If loading succeeds but the user task fails, capture the fixed input fixture, prompt revision, configured backend and observable backend evidence, output, validation rule and fallback state. A successful backend configuration request is not proof that the requested accelerator executed. The repository does not contain the raw real-device dataset required for performance or broad compatibility claims; troubleshoot the recorded combination and do not publish speed, minimum-RAM or device-support conclusions. Process and lifecycle failures need separate reproduction too: cancel work, leave and return to the screen, recreate the Activity, close the session if the runtime requires it, and run a second request. A first successful output does not prove cleanup or recovery. Never change ABI filters, minification, model file, backend and lifecycle simultaneously; otherwise a green run does not identify the cause. Make one reversible change, rerun the same fixture, and preserve both the failed and successful records. Keep private prompts and transcripts out of public logs; share only reviewed diagnostics through an appropriate support path. The practical sequence is: reproduce on the exact installed artifact; save build and environment identity; identify the earliest failing stage; choose a tool suited to that stage; make one hypothesis-driven change; repeat the same task and recovery path; and state what remains untested. A useful report says “APK built, install succeeded, native load failed on the recorded ABI” rather than “Android is unsupported.” Distinguish facts from hypotheses and keep the next check falsifiable. This procedure diagnoses boundaries; it is not evidence that all devices, artifacts, runtime versions, or Android releases are supported.

A release build succeeds but the installed local model never becomes ready

A developer installs a release APK on one device after the debug build worked in an emulator. The app opens, then displays a generic model error. The team has changed ABI filters and backend settings together before, and cannot tell whether the package omitted a library, the loader rejected a dependency, the model path is wrong, or initialization failed.

Decision

Freeze the installed APK, device and runtime identities, reproduce once, capture the first failure, and classify it before changing any build or model setting.

Expected outcome

The next action targets a verifiable boundary; no broad compatibility, performance, or model-support statement is inferred from a successful compilation or one device run.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Build and release artifact identities
• Stage-specific reproduction steps
• Failure, fallback, and recovery records

A release claim is valid only for the recorded configuration and acceptance set. Generalization requires additional records.

Implementation workflow

1. Freeze the tested artifacts. Record commit, Gradle variant and task, resolved runtime, artifact revision and format, APK or bundle identity, installation route, Android build, device ABI, and whether the run is debug or release.
2. Name the earliest failure stage. Use package-manager output, app launch result, first Java/Kotlin exception, native loader trace, model initialization result, backend evidence, and fixture outcome to identify where the sequence first stops.
3. Inspect the artifact that was installed. Use APK Analyzer to review the final manifest and native-library paths, compare release and debug outputs, and confirm the installed package is the one just examined; packaging presence alone does not prove the library can load.
4. Test one hypothesis with one change. Choose the stage-matched documentation and vary one input only, such as the packaged ABI, library dependency, runtime revision, model path, or initialization owner. Preserve the original failure and do not remove unrelated evidence.
5. Repeat task, cleanup, and recovery. Rerun the same non-sensitive fixture, record output and validation, cancel or close using the documented lifecycle, then submit the task again to check that the process is in a known state.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• The diagnostic record identifies the tested build, installed artifact, device/OS, ABI, runtime and exact first failing stage.
• Each experiment changes one documented factor and preserves the before/after artifact identity and complete failure output.
• A runtime or model claim is limited to the recorded fixture and configuration; compilation or package inspection alone is never called device compatibility.
• Private prompts, transcripts, credentials and user content are excluded from public diagnostic logs.

Decision table

Failure patterns to prevent

• Applying build fixes to runtime errors
• Calling successful compilation device support

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Cove benchmark method
• Android Developers — Analyze builds with APK Analyzer
• Android NDK — ABI management
• Android NDK — JNI tips and UnsatisfiedLinkError
• Android Developers — Diagnose app crashes
• Google AI Edge LiteRT-LM Kotlin getting started

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions