Migrating Signal Desktop keyring backend

Since 2024, the Signal encrypted messenger desktop app uses the Electron safeStorage API to protect its database encryption key. On Linux systems, this means that the freedesktop.org Secrets API is used, which on GNOME is provided by GNOME Keyring, but on KDE is provided by KWallet. This causes Signal Desktop to be unable to decrypt its database when migrating from GNOME to KDE, or vice versa, giving the error message:

Database Error

Unable to access the database encryption key because the OS encryption keyring backend has changed from kwallet6 to gnome_libsecret. This can occur if the desktop environment changes, for example between GNOME and KDE.

Please switch to the previous desktop environment or try to run signal with the command line flag –password-store="kwallet6"

It is possible to permanently migrate the database key from one keyring backend to the other. Using signalbackup-tools, we can obtain the plaintext database key:¹

$ signalbackup-tools --showdesktopkey
signalbackup-tools (signalbackup-tools) source version 20250812.134512 (SQLite: 3.50.3, OpenSSL: OpenSSL 3.5.1 1 Jul 2025)
Signal Desktop key (hex): 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

After making a backup of ~/.config/Signal, we can then modify ~/.config/Signal/config.json, which normally looks something like:

{
  "safeStorageBackend": "kwallet6",
  "encryptedKey": "fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321fedcba"
}

Where fedcba… is the database key protected using the freedesktop.org Secrets API, and safeStorageBackend indicates the original keyring backend (kwallet6, kwallet5, gnome_libsecret, etc.). We can replace this file with:

{
  "safeStorageBackend": "gnome_libsecret",
  "key": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

Where 123456… is the plaintext key obtained from signalbackup-tools, and gnome_libsecret is the desired new keyring backend. Note the replacement of encryptedKey with key.

When Signal Desktop is next opened, the plaintext key is protected using the selected keyring backend, and config.json is overwritten with the protected key.

Further reading

• Login keyring password prompt after upgrading to 7.16.0
• PSA: Signal desktop is now encrypted at-rest, so you will need to backup your encryption key to backup your data folder. Steps to backup/restore on linux inside

Footnotes