Repair a Damaged LUKS Header with cryptsetup repair

cryptsetup repair fixes specific kinds of LUKS header corruption in place, and it only makes sense once the header is safely backed up. The examples match cryptsetup 2.7.0 from the installed cryptsetup-bin package.

Allow 15 to 30 minutes, excluding any investigation of the underlying disk. You need root access, the correct encrypted device, enough space for a binary backup, and a passphrase or key file if the repair must recover interrupted LUKS2 reencryption. This command is for LUKS metadata only, not plain dm-crypt, and it is not a general filesystem repair tool.

Warning: cryptsetup repair changes on-disk LUKS header metadata. Do not run it until the binary header backup is complete and stored somewhere separate from the device being repaired.

1. Confirm the installed command and target

Check the version and action syntax before touching the device:

$ cryptsetup --version
cryptsetup 2.7.0 flags: UDEV BLKID KEYRING FIPS KERNEL_CAPI HW_OPAL
$ cryptsetup repair --help

Build flags in the version line differ between distributions; this system reports 2.7.0. Set the target explicitly rather than trusting a guessed partition name:

DEVICE=/dev/mapper/REPLACE_WITH_THE_LUKS_DEVICE
printf 'Target: %s\n' "$DEVICE"
sudo cryptsetup luksDump "$DEVICE"

Replace the value with the real LUKS device path. Read the output and confirm its UUID and metadata type. If luksDump cannot identify the device, stop: a repair command cannot compensate for picking the wrong disk.

Checkpoint: You have confirmed the device and recorded whether it is LUKS1 or LUKS2. Run the command against the encrypted device itself, not a mounted filesystem inside it.

2. Create the mandatory binary header backup

Pick a backup path on storage that stays available if the target device fails. A header backup contains the LUKS header and keyslot area, so protect it like sensitive cryptographic material:

BACKUP=/secure/backup/REPLACE_WITH_A_UNIQUE_NAME.luks-header
sudo cryptsetup luksHeaderBackup "$DEVICE" \
  --header-backup-file "$BACKUP"
sudo chmod 600 "$BACKUP"
sudo stat -c '%n %s bytes' "$BACKUP"
sudo sha256sum "$BACKUP"

Run it uninterrupted: one operation, start to finish.
Check the size: stat should report a non-zero file.
Keep the checksum: store it with your maintenance record so you can detect accidental changes to the backup.
Never co-locate it: do not put the backup on the same encrypted volume if that volume is the only copy of the data you are trying to recover.

The backup is not a passphrase reset and it does not decrypt the data. Do not email it, upload it to an untrusted service, or leave it world-readable.

3. Stop at the repair boundary

Before the repair, stop any workflow that might write to the target metadata. If the LUKS device is part of a live mapping, schedule a maintenance window and follow your system's procedure for unmounting and closing it. The repair command does not fix filesystems, check mounted data, or validate an application.

Do not add --disable-locks just because the command is inconvenient. The manpage limits that option to LUKS2 and warns against it unless metadata locking is impossible in a restricted environment where /run cannot be used. Disabling locks can allow concurrent metadata access.

4. Run the repair with the narrowest options

For an ordinary attempt, use the target and, when known, enforce its metadata type:

sudo cryptsetup repair --type luks2 "$DEVICE"

Use --type luks1 for a confirmed LUKS1 device. If you do not know the type, go back to the luksDump output rather than guess. The command currently supports LUKS devices and fixes only some basic corruptions of an unused keyslot; it changes the LUKS header, not keyslot data.

printf 'repair exit status: %s\n' "$?"
sudo cryptsetup luksDump "$DEVICE"

A successful return is status 0. The second command is a read-only inspection: compare its metadata with your pre-repair record. Success does not mean every possible corruption was repairable, and it does not prove the filesystem or the encrypted data is healthy.

5. Handle interrupted LUKS2 reencryption

cryptsetup repair also upgrades LUKS2 reencryption metadata by adding a metadata digest, and it can recover an interrupted reencryption segment so reencryption can continue later. That recovery needs verification of the reencryption keyslot.

If cryptsetup asks for a passphrase, enter the key for the relevant LUKS keyslot at the terminal. For a protected key file, pass it explicitly:

KEYFILE=/secure/keys/REPLACE_WITH_THE_KEY_FILE
sudo cryptsetup repair --type luks2 \
  --key-file "$KEYFILE" \
  "$DEVICE"

Use --keyfile-size when the key file contains trailing data that must not be read, and --keyfile-offset when the key starts a known number of bytes in. The maximum key file size on this installation is 8192 kB. Never put a real passphrase directly in a shell command: it can land in shell history or process listings.

For an interactive prompt that must not hang, use a timeout such as --timeout 30. It has no effect with --key-file. Avoid --batch-mode as a casual default: it suppresses confirmation questions and also disables passphrase verification unless --verify-passphrase is supplied.

6. Restore only once you have decided to roll back

Restoring overwrites the current LUKS header and keyslot area with the backup. It is destructive to any metadata written since the backup, so record the current state first if it is still readable. Restore only the verified backup that belongs to this exact device:

sudo cryptsetup luksHeaderRestore "$DEVICE" \
  --header-backup-file "$BACKUP"

Afterwards, run sudo cryptsetup luksDump "$DEVICE" and test the expected key or mapping through your normal, documented activation procedure. If the backup is missing, corrupted or from another device, do not guess at a restore: preserve the device for specialist recovery instead.

Common traps

Wrong target: a familiar /dev/sdX name can change after reboot. Confirm the UUID and use stable device identification.
Confusing header repair with data repair: this command does not fix a filesystem, bad sectors or lost key material.
Expecting every corruption to be fixable: the supported cases are limited, especially for unused keyslot metadata.
Leaking a key: keep key files and header backups restricted, and never put passphrases in command arguments.
Forgetting the exit status: capture $? immediately; a later inspection command has its own status.

Done means

Version and target confirmed: the installed version and target UUID were checked.
Backup verified: a non-zero binary header backup exists, permissions restricted.
Repair completed or preserved: the confirmed LUKS type was used and status 0 returned, or the failure was preserved for investigation.
Metadata readable: luksDump can read the post-repair metadata.
Key handled safely: any reencryption recovery used the correct key without exposing it in shell history.
Rollback known: you know exactly which backup would restore the pre-repair header.