Support

1. Email support

support-luksmith@protonmail.com

Include where you were and what you saw:

• your macOS version (Apple menu → About This Mac)
• which build you installed: the Mac App Store one, or the Homebrew installer;
• the drive, and how it was made: filesystem type (ext4), or LUKS(1/2) and the encryption scheme (aes-xts-plain64)
• the exact wording of anything Luksmith showed you, and the exact error macOS gave if it was macOS that refused
• if a drive will not open, please get the log lines from step 2 below.

A plain description of what you did and what happened

2. The log to send when a drive will not open

The filesystem extension writes a few lines to the system log: mount timings, and the errors it hit. To collect the last ten minutes of it run:

log show --last 10m --info --debug --predicate 'subsystem == "com.bay.luksmacos"'

Paste the output into your mail (or as a TXT file). If the attempt was earlier, widen the window with --last 2h.

3. Three things to check before you write

These account for most reports, and each takes a minute:

• The filesystem extension is switched on. macOS requires this once, by hand. To do so follow these steps: System Settings → General → Login Items & Extensions → File System Extensions, then turn on Luksmith. Until it is on, Luksmith won't work.
• Your drive is in a shape Luksmith opens. The format list on the home page is the complete answer: ext2, ext3 or ext4, inside a LUKS1 or LUKS2 container, or inside no container at all. LVM, dm-integrity, reencryption still in progress, and keyfile or token unlock are outside it, and no setting makes them work.
• (For App Store purchases ignore this part) Writing needs a licence. A fresh install reads drives and does not write to them. You need to add the key under Settings, then eject and reconnect the drive.

4. The drive does not appear, or nothing happens

• A plain ext drive has nothing to unlock. It mounts on its own a moment after it is attached.
• A LUKS drive brings Luksmith forward with the unlock window by itself. If no window appears, first check that macOS sees the hardware in Disk Utility, or with diskutil list. If the device is there and Luksmith never reacts, send the log from step 2.
• A drive whose LUKS header is kept in a separate file looks like empty media to macOS and will never come forward on its own. Pair the header file with the drive under Detached headers in the main window, then unlock.
• Unplugged while the unlock window was waiting leaves that attempt dead; Luksmith says the passphrase arrived after the drive stopped waiting. Plug the drive back in and unlock again; nothing is lost by doing so.

5. The passphrase is refused

• Copy and paste is fine, but an invisible trailing space or newline in a pasted passphrase counts as part of it. Retype it by hand once to rule that out.
• Confirm the passphrase still works elsewhere: on a Linux machine, cryptsetup luksOpen /dev/sdX name on the same drive. If it is refused there too, the passphrase or the header is the problem rather than Luksmith’s reader.
• Keyfiles and tokens are not supported. A drive set up to need one cannot be opened by Luksmith.

6. It opens read-only, or a write fails

• Read-only is the normal state without a licence, not a fault. See step 3 for how writing is turned on in each build.
• If you have paid and a drive still refuses to write, say so in the email so I can resolve the issue.
• A copy that stops with a permission error is usually the file or folder’s own owner and mode bits. Those live on the ext4 volume and travel with the drive; Finder’s Get Info shows what macOS reads from it, and any change you make there is a change to the drive. Send the exact message if it is not one of those.
• A copy that stops with the disk full means what it says, though the figure macOS shows is optimistic: free space is read from the ext4 metadata on the drive, which counts the few percent that ext reserves for root, so Finder can offer to copy slightly more than the filesystem will allocate. A Linux machine reports the same drive as having less free space for that reason.

7. The drive is busy, or it will not eject

• Eject from Luksmith, in the window or the menu bar. It unmounts the volume and powers the drive down in one step, and waits for writes to finish, which is the part that matters.
• “The drive is still in use” means exactly that: a window, a copy, an editor or a terminal still has files open on it. Close them, then eject again. “The drive is busy” is the same thing on the way back in; wait a moment and retry.
• Never force-eject a drive that was being written to, and never unplug one that is still mounted.

8. Unplugged or power-cut while writing

Reading is always safe, and unplugging a drive you only read doesn't lose your data. If a write was in flight, the ext4 journal is meant to replay at the next mount, and Luksmith replays a dirty journal when it mounts the drive. The journal replay is not a guarantee that everything is protected and recovered. It only works if the drive commits the journal before the data it describes, and macOS gives the extension no way to force that order, so a power loss at the wrong moment can leave damage that Luksmith cannot repair.

To repair for that damage you would run e2fsck on a Linux machine. macOS cannot repair ext4, and neither can Luksmith. If the drive holds anything you cannot lose, take a copy first, with Disk Utility or dd, and repair the copy rather than the only image of the drive. No recovery service can be offered by email, and pretending otherwise would waste your time.

9. Your licence

• A direct purchase arrives as a key beginning LUKSMITH-, emailed from keys@luksmith.app within a minute or two of payment. If it has not arrived, check the junk folder first, then email the support address with the address you paid with and the order number from the receipt. The key is re-sent from the order record; there is nothing to look up and nothing to pay again.
• A key you have added is kept in your Mac’s keychain, so updating the app does not lose it.
• A licence is per person rather than per Mac: the key works on every computer you are the primary user of, which is what the licence agreement grants.
• The Mac App Store build never asks for a key. It is the paid build; the purchase is held by Apple against your Apple Account.

10. Where fixes appear

Every release lists what changed on the releases page. If a bug you reported is fixed, the entry will say so. The app itself makes no network connection and never phones home, so there is nothing to subscribe to and no account to keep.