Encountering the message "keystore was tampered with, or password was incorrect" typically indicates a mismatch between the keystore integrity check and the credentials supplied. This alert is common when attempting to open or sign an Android application and signals that the file has been altered or the wrong secret was used.
Below is a structured overview of causes, verification steps, and remediation options to help you diagnose the issue quickly and securely.
| Cause Category | What Triggers It | Quick Indicator | Immediate Action |
|---|---|---|---|
| Password Mismatch | Wrong store password, key password, or both | Failure at store or key level during apksigner or keytool | Verify case-sensitive passwords and entry order |
| File Corruption | Incomplete copy, interrupted transfer, or disk errors | Checksum mismatch or open errors in multiple tools | Re-acquire or re-generate the keystore from a known good source |
| Tampering or Modification | Unauthorized edits to keystore bytes or entries | Security warnings, unexpected signature failures | Reject the file and use a trusted backup or re-sign with a clean keystore |
| Tooling or Format Changes | Migration between Java keytool, Android Keystore, or new apksigner versions | Errors only on specific platforms or tooling | Standardize tooling versions and export/import parameters |
Verifying Keystore Integrity
Before retrying with adjusted credentials, confirm whether the keystore file itself is intact. Even a small byte-level change can trigger the tamper detection, and integrity checks are designed to catch such alterations reliably.
Using keytool to List Entries
Running keytool with the correct store password allows you to test access without modifying anything. If keytool reports tampering, the file is likely damaged or was modified after creation.
Comparing Checksums
Generate a hash of the keystore on the system where it was originally created and compare it with the current copy. Mismatched hashes strongly suggest tampering or corruption during transfer or backup operations.
Common Triggers and Root Causes
Understanding the typical sources of this alert helps narrow down whether the issue is user error, environment change, or actual security concern. Reviewing these scenarios can save time and prevent repeated failed attempts.
Typographical Mistakes and Case Sensitivity
Store passwords and key passwords are case-sensitive and often long, mixing letters, numbers, and symbols. A single mistyped character is enough to produce the tamper warning rather than a plain access denied message.
Keystore Movement Across Systems
Moving a keystore between development machines, CI servers, or signing services can introduce line-ending conversions, encoding issues, or partial writes. Even binary-safe transfers may mishandle the file if the toolchain differs across platforms.
Secure Recovery and Reuse Practices
Recovering from this state requires balancing security with availability. You must ensure that no unauthorized party benefits from a potentially exposed keystore while still regaining legitimate access to your applications.
Using Known Good Backups
If you maintain a verified backup created on the same machine and toolchain, restore it to a temporary location first. Confirm that the restored file passes integrity checks before using it for release builds or publishing.
Re-creating the Keystore When Necessary
When no valid backup exists, you may need to generate a new keystore and re-sign published applications through the appropriate platform recovery flow. Treat this as a last resort, since lost keystores can permanently block updates to existing apps.
Best Practices for Keystore Management
- Keep multiple encrypted backups of the keystore in geographically separate secure locations.
- Record the exact keytool and apksigner versions used for each release keystore.
- Use environment variables or secret managers for passwords instead of hardcoding them in scripts.
- Verify checksums in CI before any signing or verification step.
- Document recovery procedures and test them periodically to ensure timely restoration.
FAQ
Reader questions
Why does my automated build suddenly report tampering when the keystore worked before?
A change in the build environment, such as a library update, JDK migration, or altered file path, can silently corrupt the keystore during packaging or checksum verification.
Can this error appear if I use the Android Keystore system instead of a JKS file?
Yes, similar integrity checks apply when keys are stored in the hardware-backed Android Keystore, and tamper detection may surface through related APIs when unexpected modifications are detected.
Is it safe to lower integrity checks to bypass this warning?
Disabling integrity verification is strongly discouraged, as it removes tamper detection that helps protect against supply-chain attacks and accidental file corruption across pipelines.
How can I prevent this in continuous integration pipelines?
Store the original keystore as a secure artifact, use checksum validation before signing, and lock toolchain versions to ensure consistent behavior across runs.