Prepare the original bundle and signing context
Use an AAB from a known build and obtain bundletool from the official Android tooling distribution. Keep the bundle, source revision and signing configuration together. Do not put private keystore passwords into shared shell history or analysis reports.
Generating APKs locally does not necessarily reproduce the signing certificate of APKs Google Play delivers. Play App Signing can use a different app-signing key from your upload key. Signing overview.
Generate a universal package for a local check
An illustrative command is:
java -jar bundletool.jar build-apks \
--bundle=app-release.aab \
--output=local-universal.apks \
--mode=universal
Configure the signing options appropriate to your test. Without explicit release signing, do not assume the output carries your production identity. The .apks output is an archive; inspect it and extract the generated universal APK using an archive tool. bundletool reference.
Use device-specific output when delivery matters
For a connected test device, you can generate an APK set with a device specification and use bundletool to install it. This helps reveal configuration-specific problems that a universal APK can hide, such as missing native libraries or resources.
A universal APK can also include only features configured to participate in that output. It is not a complete substitute for testing on-demand feature or asset delivery through the intended distribution channel.
Diagnose generation failures at the right layer
| Symptom | Check first |
|---|---|
| Bundle cannot be read | File integrity, bundle format and bundletool compatibility |
| Signing failure | Keystore path, alias and credentials |
| APK installs but login fails | Certificate fingerprints and backend registration |
| Device-specific install fails | Device specification, SDK/ABI support and complete split set |
Do not rename the AAB, hand-copy module contents into a ZIP or sign only one file from a mismatched package set.
Verify the generated artifact
Inspect the resulting APK's application ID, version and SDK declarations. Verify signing separately, install on a test device and exercise the relevant features. Label your record “generated locally with bundletool” rather than “downloaded from Play” so the certificate and delivery assumptions remain clear.
APKLint's AAB Analyzer is useful for inspecting the publishing container. It is not a replacement for bundletool's APK generation, package validation or a real installation test.
Record the generation choices with the output
For a release candidate, retain the source AAB hash, bundletool version, selected mode and signing-certificate fingerprint beside the generated APK archive. Store the command with secrets omitted. These details distinguish a universal development check from a device-targeted test and let another developer reproduce the selection without assuming that every file called release.apks was generated identically.
Suppose a local universal APK signs in correctly, but a Play-installed version does not. Compare the signing context and backend registration before rewriting the sign-in UI. The local build may use a certificate different from the store-delivered app. That possibility is a hypothesis to verify, not a universal explanation for every login failure; capture the actual error and relevant configuration.
Inspect the generated result independently
After generation, list the archive and identify the intended APK or split set. Check its application ID and version against the source release record, then verify signing with a signing-aware tool. Open the package through an independent analyzer so an accidentally selected output from an older run is caught before the installation test. Use a new output directory or explicitly manage the prior artifact rather than relying on timestamps alone.
The official bundletool repository is the source for the tool and release information. Pin the version used for a reproducible pipeline and revisit compatibility deliberately when updating it. A successful invocation is evidence that generation completed under that tool's rules; it does not certify store policy, backend configuration or all device delivery paths.
Keep universal-mode results separate from tests of dynamic feature delivery. If an optional feature matters, exercise its actual installation and use through the intended channel. A broad local APK can hide a selection issue that appears only when resources or modules are delivered separately. Report both the packaging mode and the tested user flow when describing the generated APK as usable.
Sources and further reading
Reference review: 29 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
