# Recover a KeePassXC key file

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/rehearse-keepassxc-key-file-recovery/)

Restore a test database key file from an encrypted KeySigner backup and confirm that it still opens KeePassXC.

## Before you start

**KeySigner macOS test build with local key file commands and KeePassXC 2.8.0**

- Use a disposable KeePassXC database with a password, an empty KeySigner key file store in a separate test setup, and private local folders for the XML key file and encrypted backup.
- [Check the KeePassXC version](https://keysigner.io/integrations/setup-requirements/#check-versions-keepassxc)

## Data and access

- **Shared or checked**. KeySigner delivers a restored copy of the test database’s key file. KeePassXC uses that file and the database password to open the database.
- **Check separately**. Every delivered copy remains usable with the matching password. Replace the key file in KeePassXC if a copy is exposed.

## 1. Create a test key file

Open your test KeySigner vault on the Mac. In Terminal, list the key files. Replace REVISION with the revision in that response to create a key file labeled for your test database.

~~~
keysigner authenticator keyfile-list --json
keysigner authenticator keyfile-create 'Recovery test' 'test.kdbx' REVISION --json
~~~

**Check.** The create response contains the key file ID and a new revision. Use both for the next command.

## 2. Add the file to the test database

Replace KEY_FILE_ID and REVISION with the values from the create response to save the XML file to a new path in a private local folder. In KeePassXC, keep the database password and add this file under Database Settings, Security. Lock the database and check that the password and file together open it. Clear the key file selection and check that the password alone is rejected.

~~~
keysigner authenticator keyfile-deliver KEY_FILE_ID REVISION ./test.keyx reusable-copy
~~~

**Check.** Open the same test entry with the password and the new file. After locking, check that KeePassXC rejects the password alone.

## 3. Back up the KeySigner key files

Run the backup command from a private local folder and enter a separate backup passphrase at the hidden prompt. Keep the encrypted backup and its passphrase available for the rehearsal. Keep the test database and original key file until you confirm recovery.

~~~
keysigner authenticator keyfile-backup ./key-file-backup.age
~~~

**Check.** Find the encrypted backup at the path you gave the command before continuing to the separate vault.

## 4. Restore in a separate test vault

Open an empty KeySigner key file store in a separate test setup. Copy the encrypted backup there and preview it using the backup passphrase. Match the key file label. Replace REVIEW_HASH and REVISION with the review hash and destination revision from the preview before applying it.

~~~
keysigner authenticator keyfile-backup-review ./key-file-backup.age --json
keysigner authenticator keyfile-backup-restore ./key-file-backup.age REVIEW_HASH REVISION --json
~~~

**Check.** The preview shows the expected label. After applying it, use the restore response for the ID and revision in the next step.

## 5. Open the database with the recovered file

Replace KEY_FILE_ID and REVISION with the values from the restore response to deliver the restored file to a new private path. Open the test database in KeePassXC with its password and the restored file.

~~~
keysigner authenticator keyfile-deliver KEY_FILE_ID REVISION ./restored.keyx reusable-copy
~~~

**Check.** Confirm the database opens to the same test entry. An unrelated file should fail even with the correct database password.

## Check your result

Check that the recovered file and the database password open the same test entry. Each delivered file is a reusable copy of the same factor and works while KeySigner is locked. KeySigner cannot revoke a copy. If you lose control of one, replace the key file in KeePassXC and check that the old file no longer opens the updated database.

### What we tested

**Tested on November 17, 2026.** KeePassXC 2.8.0 opened a local test database with the generated key file and then with the file restored from backup. It rejected a missing or wrong key file and an incorrect database password. A delivered copy also opened the database while KeySigner was locked.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### KeySigner refuses the backup review

Confirm the destination key file store is empty and the backup is a KeySigner key file backup. Preview again in the intended destination if you switched test setups or the revision changed.

## Tools in this guide

- [KeePassXC](https://keysigner.io/integrations/keepassxc/)
  - [Check database unlock factors and recovery](https://keepassxc.org/docs/KeePassXC_UserGuide)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#keepassxc)

## Setup instructions

- [Add a key file in KeePassXC](https://keepassxc.org/docs/KeePassXC_UserGuide#_database_settings)
- [Copy sign-in codes from KeePassXC](https://keysigner.io/integrations/guides/test-sign-in-code-import/)

[More guides for this task](https://keysigner.io/integrations/tasks/rehearse-recovery/)
