When FileVault full-disk encryption is active on a Mac, the primary APFS system container remains encrypted and locked when the machine powers on. To allow users to authenticate and unlock their storage, macOS relies on a dedicated, unencrypted auxiliary partition within the APFS container: the Preboot volume. The Preboot volume holds the pre-login kernel cache, user account avatars, login window interfaces, and cryptographic unlock credentials.
Following operating system updates, user account password changes, or manual disk migrations, the Preboot volume can occasionally become desynchronized from the main operating system volume. This manifests as missing user login avatars, persistent FileVault unlock errors, or prolonged boot delays. To resolve these issues, macOS includes a specialized disk management command: diskutil apfs updatePreboot. This guide explains how the Preboot volume functions, when to run updatePreboot, and step-by-step execution syntax.
How the APFS Preboot Volume Functions
In standard APFS container architecture, multiple logical volumes share a common storage pool:
- Macintosh HD (System): A read-only, cryptographically signed snapshot of the operating system files.
- Macintosh HD – Data: The encrypted volume containing user accounts, applications, and personal data.
- Preboot: Stores bootloader payloads, FileVault login UI assets, and encrypted key-wrapping data.
- Recovery: Contains recoveryOS diagnostic utilities and reinstall environments.
When you update user credentials, change profile pictures, or update security policies, macOS automatically updates the Preboot volume. If this automated sync fails, the login screen displays outdated account information or refuses valid passwords until manually rebuilt.
Executing diskutil apfs updatePreboot
Because rebuilding boot caches alters EFI and FileVault security manifests, the command requires superuser privileges via sudo:
1. Identify the Target APFS Volume
First, list the mounted APFS volumes to identify your system volume identifier:
diskutil apfs listLocate your primary boot volume (e.g. disk3s1 or /System/Volumes/Data).
2. Run updatePreboot
Execute the update command targeting your primary system disk:
sudo diskutil apfs updatePreboot /Alternatively, target the specific volume identifier:
sudo diskutil apfs updatePreboot disk3s1Understanding the Terminal Output
When executed, updatePreboot performs several sequential maintenance operations:
Started APFS operation on disk3s1 Macintosh HD
Finding the APFS Volume Group...
Mounting auxiliary Preboot volume...
Updating Preboot for Target Volume UUID: A1B2C3D4-E5F6-7890-ABCD-1234567890AB
Writing EfiLoginUI resources...
Saving Secure Token metadata for 2 authorized users...
Writing KernelCache and boot manifests...
Unmounting auxiliary volume...
Finished APFS operationKey Troubleshooting Scenarios for updatePreboot
| Symptom / Problem | Underlying Cause | Remediation Step |
|---|---|---|
| Missing User on FileVault Screen | User was recently created or granted admin rights but lacks a SecureToken in Preboot | Run sudo diskutil apfs updatePreboot / followed by sysadminctl -secureTokenStatus <user> |
| Old Profile Picture at Login | EfiLoginUI cache retains cached avatar bitmap | Execute updatePreboot to overwrite cached UI assets |
| Slow FileVault Authentication | Corrupted Preboot boot manifest or incomplete OS patch cache | Rebuild Preboot cache from recoveryOS Terminal |
Running updatePreboot in recoveryOS
If your Mac cannot boot into normal macOS due to a corrupted Preboot volume:
- Boot into recoveryOS (hold Power button on Apple Silicon; hold Cmd + R on Intel).
- Open Disk Utility, select your data volume, and click Unlock to decrypt it using your admin password.
- Quit Disk Utility and launch Terminal from the Utilities menu.
- Run:
diskutil apfs updatePreboot /Volumes/Macintosh HD - Restart the computer normally.