Debugging log · Signing

"Keystore was tampered with, or password was incorrect"

Few build errors raise the pulse like this one. You're trying to sign a release, and the tooling tells you your keystore may have been tampered with — the file that, if truly lost, ends your ability to update the app. Take a breath: in practice this message is almost never about tampering. It's the same error Java throws for a simple wrong password, and the wording is just alarmist.

The short version: this is Java's generic "I couldn't open the keystore" error. The overwhelmingly common cause is an incorrect password — often the store password confused with the key password. Verify with keytool before assuming the file is damaged.

The error

java.io.IOException: Keystore was tampered with, or
password was incorrect
  ... Caused by: java.security.UnrecoverableKeyException:
      Password verification failed

Two passwords, not one

This is the root of most cases. A keystore has two separate passwords, and they are not required to be the same:

Store password (storePassword) — unlocks the keystore file itself.
Key password (keyPassword) — unlocks the individual key inside it, identified by its alias.

Because many people set both to the same value when creating the key, it's easy to forget there are two — until a project where they differ, and you supply one where the other belongs. If the error mentions UnrecoverableKeyException specifically, the store opened fine and it's the key password that's wrong; if the store itself can't be read, the store password is the suspect.

Verify with keytool before panicking

Test the store password directly, outside your build:

keytool -list -keystore my-release-key.jks

If that prompts and then lists your aliases, the file is fine and the store password is right — so your problem is in the build config (probably the key password or alias). If it fails here too, the store password you have is wrong.

Then check the specific key and confirm the alias is spelled exactly as the build expects:

keytool -list -v -keystore my-release-key.jks -alias my-alias

The usual culprits

Store vs key password swapped — by far the most common. Try each in the other's place.
Wrong alias. An alias that doesn't exist can surface as a password failure rather than a clear "no such alias".
Invisible characters. A trailing space or newline copied from a password manager or a .properties file counts as part of the password.
Escaping in properties files. Special characters (notably \) need escaping in a Java properties file; the value Gradle reads may not be the value you typed.
The wrong keystore file. Several .jks files with similar names, and the build is pointed at last year's one.
A truly corrupted file — real, but rare. Usually from a bad copy, a partial download, or Git treating it as text. Keystores are binary; restore from your backup.

If the file is genuinely gone or unopenable and it's your upload key, don't panic — with Play App Signing you can request an upload key reset and carry on. That safety net exists precisely for this. The key you can't replace is the app signing key, which Google holds for you.

Habits that prevent the next occurrence

Record both passwords and the alias the day you create the key — in a password manager, not memory.
Keep credentials out of the repo. Put them in a local properties file (ignored by Git) or environment variables, and read them in signingConfigs.
Back up the keystore somewhere durable and offline, and verify the backup opens with keytool.
Mark it binary in .gitattributes if it must live in a repo at all, so nothing mangles it as text.

File names and aliases above are placeholders — substitute your own.