KeyPlus troubleshooting

KeyPlus says the vault cannot be unlocked

Confirm that you are using the master password belonging to the selected vault or backup. AES-GCM authentication deliberately produces the same general failure for a wrong password and modified ciphertext. Do not repeatedly edit the JSON envelope or replace it with an unverified copy.

If the file was recently replaced, preserve the active file and inspect the encrypted files in the backups directory. Restore only a backup whose password and contents you can validate.

KeyPlus reports an unsupported vault version

The file identifies a format or cryptographic profile this build does not support. Do not change its version number manually: doing so does not migrate the encrypted data. Keep the original file and use a compatible KeyPlus build or an official migration path.

The vault changed in another process

Another KeyPlus process wrote the vault after this process unlocked it. Lock or close the stale process, reopen the vault, and repeat the intended change. This check prevents older decrypted state from silently overwriting newer entries.

If KeyPlus reports that the vault is busy, close other KeyPlus processes and retry after their write completes. Check that the data directory is writable and has free disk space if the problem persists.

A 0.2 migration is not offered

The chosen directory must contain both auth.db and vault.json. Because 0.2 used its launch directory, the files may be in a former checkout, terminal working directory, or package launch location. KeyPlus deliberately does not search the whole home directory. Locate the pair yourself and pass its folder with keyplus --migrate <directory> or the GUI migration chooser.

Migration cannot install over an existing 0.3 vault. Preserve the existing vault and backups before changing data locations. Never delete the legacy pair until the new vault has been opened and independently backed up.

A backup does not contain recent changes

Timestamped backups are snapshots, not synchronization. last-good.vault is the valid envelope from immediately before the latest successful replacement; it is not guaranteed to contain the newest entry. Older backups may also use an earlier master password.

Use CLI command backups to list files currently present in the application backup directory. A damaged existing last-good.vault does not prevent the next successful mutation from replacing it with the valid pre-mutation active vault.

Restoration replaces the entire active document and does not merge entries.

The GUI does not start

For source installs, confirm Python 3.10 or later and reinstall the project so PySide6 is present. Try keyplus to determine whether the core CLI can start, then run keyplus --gui from a terminal to retain any startup error. Linux also requires a working graphical session and the libraries required by Qt.

A session locked unexpectedly

The default idle timeout is five minutes. Unlock again with the master password. The GUI checks expiry periodically; the CLI checks when the next core operation is requested. Locking does not close the process—it invalidates its in-memory vault session.

Reporting a problem

Include the KeyPlus version, operating system, package type, launch command, and exact synthetic reproduction steps. Do not post master passwords, real credentials, decrypted screenshots, or vault files. Use a private GitHub security advisory for suspected vulnerabilities.