OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
apps-services medium common DISPUTE

Fix "swapon failed: Invalid argument" for a swap file on btrfs

archomarchybtrfsswap
AUDITED Audited against its sources and confirmed accurate. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

Kernel strings confirmed in fs/btrfs/inode.c on torvalds/linux master: 'swapfile must not be copy-on-write', 'must not be compressed', 'must not have holes', 'must be on one device', and fs/btrfs/ioctl.c returns -ETXTBSY with 'cannot snapshot subvolume with active swapfile'. On this 4.0.4-1 workstation / is mounted compress=zstd:3,subvol=/@ (findmnt and /etc/fstab), zram0 is active at priority 100 from /usr/share/omarchy/default/systemd/zram-generator.conf.d/90-omarchy.conf, and /usr/share/omarchy/bin/omarchy-hibernation-setup creates a /swap subvolume, runs btrfs filesystem mkswapfile into /swap/swapfile, adds 'defaults,pri=0' to fstab and wires resume via /etc/limine-entry-tool.d/resume.conf, exactly as the record says. btrfs-progs 7.1 supports mkswapfile --size and --uuid clear (btrfs filesystem mkswapfile --help), matching the Arch wiki Btrfs swap file section. omarchy-snapshot create exists and runs snapper per config. Not exercised: no swap file was created or activated. One caveat for the reader, not a defect: if a smaller /swap/swapfile already exists, omarchy-hibernation-setup reuses it rather than resizing it to RAM size, so anyone who wants hibernation should run that script instead of the manual steps.

RISK

Deleting the wrong fstab line can leave a mount missing at boot. Read the grep -n output before running the sed.

Symptom

After following a generic swap file guide (fallocate or dd, then mkswap):


swapon: /swapfile: swapon failed: Invalid argument

The kernel log says one of swapfile must not be copy-on-write, swapfile must not be compressed, swapfile must not have holes or swapfile must be on one device. Or the swap works but snapshots of / now fail with cannot snapshot subvolume with active swapfile (Text file busy), which on Omarchy breaks the pre-update snapshot.

Cause

btrfs accepts a swap file only if it is NOCOW, uncompressed, fully preallocated with no holes, and on a single-device filesystem. A file created the ext4 way is copy-on-write, and on Omarchy root is mounted compress=zstd:3, so it fails activation. A swap file placed directly in @ also blocks every snapshot of @ while it is active.

Fix

Find out why first:


journalctl -k -b | grep -i swapfile
sudo btrfs filesystem show /      # more than one device means no swap file at all

Remove the broken file and its fstab line (check the line before deleting it):


sudo swapoff /swapfile 2>/dev/null
sudo rm -f /swapfile
grep -n swapfile /etc/fstab
sudo sed -i '\|^/swapfile |d' /etc/fstab

Create it the btrfs way, in its own subvolume so snapshots of / keep working. mkswapfile handles NOCOW and preallocation:


sudo btrfs subvolume create /swap
sudo btrfs filesystem mkswapfile --size 8g --uuid clear /swap/swapfile
sudo swapon /swap/swapfile
echo '/swap/swapfile none swap defaults,pri=0 0 0' | sudo tee -a /etc/fstab

**Omarchy 4:** zram already provides swap, so a disk swap file is optional. Check whether one exists before creating it (sudo btrfs subvolume show /swap, swapon --show). omarchy-hibernation-setup builds exactly this /swap/swapfile at priority 0 below zram's 100, and also wires up resume, so use it if hibernation is the goal.

On a multi-device btrfs volume use zram or a swap partition instead.

Verify

swapon --show lists /swap/swapfile, journalctl -k -b | grep -i swapfile shows no warnings, and on Omarchy omarchy-snapshot create completes.

Sources

btrfs-swapfile-swapon-invalid-argument