Skip to content

Instantly share code, notes, and snippets.

@GithubUser5462

GithubUser5462/bcachefs_mount_required_key_not_available.md

Last active November 10, 2025 01:39
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save GithubUser5462/efad2bd82a27cd46a79b2740ff7fb58e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save GithubUser5462/efad2bd82a27cd46a79b2740ff7fb58e to your computer and use it in GitHub Desktop.
Download ZIP
Resolving “Required key not available” When Mounting an Encrypted Bcachefs Volume
Raw
bcachefs_mount_required_key_not_available.md

Resolving “Required key not available” When Mounting an Encrypted Bcachefs Volume

Problem Overview

When mounting an encrypted Bcachefs filesystem (after unlocking it with a passphrase), you may encounter the error:

mount: ... Required key not available  
ERROR - bcachefs::commands::cmd_mount: Fatal error: Required key not available

This indicates the kernel could not find the encryption key needed to decrypt the volume during the mount operation. In other words, the key you provided with bcachefs unlock isn’t accessible to the mount process, causing the mount to fail.

Cause: Linux Keyring and Isolation

Bcachefs uses the Linux kernel keyring to store the encryption key in-kernel when you unlock a volume. By default, the bcachefs unlock command adds the key to your user keyring. However, the mount operation (often via the mount.bcachefs helper) may be looking for the key in a different keyring (such as the session or service keyring).

On modern systems (Systemd v233+), each service or session can have its own isolated keyring, meaning keys aren’t shared across processes by default. For example, if bcachefs unlock runs in one context (adding the key to the user keyring) but the actual mount runs in another (with a separate session keyring), the kernel reports “Required key not available” because it can’t see the key in the expected keyring. This keyring isolation is a known issue affecting encrypted mounts in Bcachefs (as well as eCryptfs and other encrypted filesystems) when not configured to share keys.

Solutions / Workarounds

Thankfully, there are a couple of ways to fix this:

Solution 1: Link the User Keyring to the Session Keyring

You can manually make the key available to the session (or mount process) by linking your user keyring to your session keyring. This is done with the keyctl utility:

  1. Unlock the volume (which adds the key to your user keyring):

    bcachefs unlock /dev/sdb

    (Enter your passphrase when prompted.)

  2. Link keyrings before mounting:

    keyctl link @u @s

    This command links the @u (user) keyring to the @s (session) keyring, so the session keyring now has access to the Bcachefs key.

  3. Mount the filesystem:

    mount -t bcachefs /dev/sdb /media/mnt

    If prompted for a passphrase again, just press Enter – you should not need to re-enter it, since the key is already in the keyring. The mount should proceed without the “Required key not available” error now that the kernel can find the key in the session keyring.

This workaround has been verified by multiple sources. For example, Arch Linux documentation notes that linking the keyrings in this way allows the mount to succeed, and Bcachefs users on the mailing list confirm that running keyctl link @u @s immediately before mounting resolves the issue.

Solution 2: Unlock into the Session Keyring Directly

As of recent versions of Bcachefs tools, you can instruct bcachefs unlock to use a specific keyring. In particular, using the -k session option will add the encryption key to the session keyring instead of the user keyring. For example:

bcachefs unlock -k session /dev/sdb

This will prompt for your passphrase and load the key into the session keyring (accessible by the mounting process) by default. After this, a normal mount -t bcachefs /dev/sdb /media/mnt should work without error, since the key is already in the correct keyring. In effect, -k session achieves the same goal as the manual keyctl link step, but in one step. The Bcachefs manual explicitly lists session as an allowed keyring for the unlock command (the default is user). Many users have reported that adding this flag when unlocking immediately fixes the “Required key not available” mount error (because the key is placed where the kernel expects it).

Solution 3: Handling Key Revocation with keyctl new_session

If you encounter the error keyctl_link: Key has been revoked after linking the keyrings, it indicates that the key was removed or revoked from the keyring. To resolve this, you can create a new session keyring, which ensures that the session is re-established, and the keyring operations are fresh.

  1. Create a new session keyring:

    keyctl new_session

    This command creates a new session keyring, ensuring that the keyring is valid and ready for linking.

  2. Link keyrings again:

    keyctl link @u @s

  3. Mount the filesystem:

    mount -t bcachefs /dev/sdb /media/mnt

    This step ensures that the mount process has access to the encryption key, resolving any issues related to key revocation.

Additional Considerations

  • Systemd Service Units: If you are mounting the Bcachefs volume via a systemd unit or at boot (e.g. in /etc/fstab or an initramfs script), be aware of the keyring isolation. In systemd v235 and later, unit files can use KeyringMode=shared to disable the per-service keyring isolation. Ensuring the unlock and mount occur in a context with a shared keyring (or explicitly linking the key as shown above in a PreExec step) may be necessary for automated boot-time mounting.

  • Bcachefs Tool Improvements: The Bcachefs developers are aware that the keyring handling is error-prone. In fact, lead developer Kent Overstreet described the keyring mechanism as “a perpetual utter headache,” and indicated they might redesign how keys are passed to the kernel (possibly avoiding keyrings altogether in the future). Until an official fix is released in the tools and kernel, using the above workarounds is the reliable solution.

Summary

The “Required key not available” error is essentially due to the encryption key not being in the right place for the mount to find. To fix it, you should either link your user and session keyrings before mounting or use the -k session flag when unlocking the Bcachefs volume. Both approaches ensure the kernel has access to your decryption key at mount time, allowing the encrypted Bcachefs filesystem to mount successfully. By implementing one of these fixes, the volume in /dev/sdb should mount at /media/mnt without further errors.

Sources: Bcachefs documentation and user reports.

Comments are disabled for this gist.