🚨 Linux Error Guide: 'swapon: swapon failed: Invalid argument' — fix the swap file or partition

Overview

You try to enable swap — on a freshly created swap file, after editing /etc/fstab, or during boot — and the kernel rejects the request:

swapon: /swapfile: swapon failed: Invalid argument

Variants point at a partition or show up during boot / systemd swap-unit activation:

swapon: /dev/sdb2: read swap header failed: Invalid argument
swapon: cannot enable swap: /swapfile: Invalid argument
Failed to activate swap /swapfile.

swapon asks the kernel to start using a file or block device for swap. Before it will, the kernel reads a swap header written by mkswap at the start of the area and validates it: signature, page size, and layout. Invalid argument (EINVAL) means that validation failed — the area was never formatted with mkswap, was formatted with an incompatible page size, is not laid out the way swap requires (the file has holes or lives on a copy-on-write filesystem), or is too small/misaligned. It is a formatting/layout problem, not a permissions or “file missing” problem.

Symptoms

• swapon /swapfile or swapon /dev/sdX fails immediately with Invalid argument.
• Boot shows Failed to activate swap for a swap unit, and systemctl --failed lists a *.swap unit.
• free -h shows Swap: 0 even though an entry exists in /etc/fstab.
• The error appears right after creating a swap file with fallocate or dd, or after migrating an image to a filesystem like Btrfs/ZFS.
• A swap partition that worked on one machine fails on another (different page size / architecture).

Common Root Causes

• The area was never run through mkswap. A file created with fallocate/dd is just data until mkswap writes the swap signature.
• The swap file has holes (is sparse). fallocate on some filesystems, or truncate, can create a file with unallocated extents; swap requires fully-allocated, contiguous-enough backing.
• The file lives on a copy-on-write filesystem (Btrfs, ZFS) without the required preparation. Btrfs needs a swap file with CoW disabled (chattr +C) and no compression/snapshots; ZFS does not support swap files at all (use a zvol).
• Page-size mismatch. A swap area formatted on a host with a different kernel page size (e.g. 64K on some arm64/ppc64le vs 4K on x86_64) has a header the current kernel rejects.
• Wrong device / mislabeled partition. The fstab entry or UUID points at something that is not a formatted swap area (a data partition, an empty new partition).
• Too small or misaligned. An area below the minimum usable swap size, or a header corrupted/overwritten.

Diagnostic Workflow

First confirm what the target actually is and whether it carries a swap signature.

# Does the target have a swap signature at all?
sudo blkid /swapfile
sudo blkid /dev/sdb2
# TYPE="swap" means mkswap ran; no TYPE (or a different one) means it did not

Check the swap file’s allocation and filesystem — the two most common file-specific traps are holes and CoW.

# Is the swap FILE sparse (has holes)?  apparent vs actual size
ls -lh /swapfile
du -h --apparent-size /swapfile
du -h /swapfile                 # if actual << apparent, it's sparse -> invalid for swap

# What filesystem is it on? (Btrfs/ZFS need special handling)
findmnt -no FSTYPE -T /swapfile

For a partition, verify page size assumptions and read the header:

getconf PAGESIZE                # current kernel page size
sudo swapon --show             # what is currently active
dmesg | tail -n 20 | grep -i swap

Now rebuild the area correctly. For a regular file on ext4/xfs, allocate real blocks (not a sparse file), lock down permissions, then mkswap:

sudo swapoff /swapfile 2>/dev/null
sudo rm -f /swapfile
# Allocate fully with dd (avoids sparse/hole issues that break swap)
sudo dd if=/dev/zero of=/swapfile bs=1M count=2048 status=progress
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

On Btrfs, disable copy-on-write on the file before writing to it (the file must be created empty, then have CoW cleared):

sudo truncate -s 0 /swapfile
sudo chattr +C /swapfile        # disable CoW; must be done while file is empty
sudo dd if=/dev/zero of=/swapfile bs=1M count=2048 status=progress
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

For a partition, point mkswap at the right device and re-enable:

sudo mkswap /dev/sdb2
sudo swapon /dev/sdb2
sudo swapon --show

Example Root Cause Analysis

An engineer added 2 GB of swap to a new VM: fallocate -l 2G /swapfile, mkswap /swapfile, swapon /swapfile. The mkswap step succeeded, but swapon returned swapon failed: Invalid argument.

Diagnosis was quick: du -h /swapfile reported only a few kilobytes actual usage against a 2 GB apparent size — the file was sparse. findmnt -T /swapfile showed the filesystem was Btrfs, where fallocate produced an unallocated (holey) file and where swap also requires copy-on-write to be disabled. The kernel refused it because a swap file must not contain holes.

The fix rebuilt the file the way Btrfs requires: create it empty, chattr +C to disable CoW while empty, fill it with dd (real allocated blocks, no holes), chmod 600, then mkswap and swapon. Swap came up immediately and free -h showed the 2 GB. The fstab entry was left as /swapfile none swap sw 0 0, and because the file was now correctly formatted it activated cleanly on the next boot. The takeaway: on modern/CoW filesystems, prefer dd over fallocate for swap files and disable CoW first.

Prevention Best Practices

• Always mkswap before swapon. Creating the file is not enough; the swap signature must be written.
• Avoid sparse swap files. Prefer dd if=/dev/zero (fully allocated) over fallocate/truncate for swap files, especially on filesystems where fallocate can leave holes.
• Handle CoW filesystems explicitly. On Btrfs, create the file empty, chattr +C to disable copy-on-write before writing, and keep it out of snapshots. On ZFS, do not use swap files at all — create a zvol and swap on that.
• Set chmod 600 on swap files so swapon does not warn and the file is not world-readable.
• Match the environment for partitions. A swap partition formatted under one page size may be rejected on a system with a different page size; re-run mkswap on the target host if you moved disks between architectures.
• Prefer UUIDs in fstab (UUID=... none swap sw 0 0) so the right area is referenced even if device names change, and test with swapon -a before rebooting.

Quick Command Reference

# Diagnose
sudo blkid <target>                 # TYPE="swap" confirms mkswap ran
du -h --apparent-size /swapfile ; du -h /swapfile   # detect a sparse file
findmnt -no FSTYPE -T /swapfile     # is it on Btrfs/ZFS?
getconf PAGESIZE                    # kernel page size (partition mismatch check)
swapon --show                       # currently active swap

# Rebuild a swap FILE on ext4/xfs
sudo swapoff /swapfile; sudo rm -f /swapfile
sudo dd if=/dev/zero of=/swapfile bs=1M count=2048
sudo chmod 600 /swapfile; sudo mkswap /swapfile; sudo swapon /swapfile

# Rebuild a swap FILE on Btrfs (disable CoW first, while empty)
sudo truncate -s 0 /swapfile; sudo chattr +C /swapfile
sudo dd if=/dev/zero of=/swapfile bs=1M count=2048
sudo chmod 600 /swapfile; sudo mkswap /swapfile; sudo swapon /swapfile

# Rebuild a swap PARTITION
sudo mkswap /dev/sdb2; sudo swapon /dev/sdb2

# Validate fstab entries without rebooting
sudo swapon -a && swapon --show

Conclusion

swapon: swapon failed: Invalid argument means the kernel could not accept the area as swap because its header or layout is wrong — almost always an unformatted file, a sparse/holey file, a copy-on-write filesystem that needs special handling, or a page-size/device mismatch on a partition. Confirm the target with blkid, check for holes with du, and rebuild it correctly: fully allocate the backing (prefer dd), disable CoW on Btrfs (or use a zvol on ZFS), then mkswap and swapon. Reference swap by UUID in fstab and test with swapon -a so it comes up cleanly on every boot.