I've needed to run btrfs balance on my single device filesystem as I was getting ENOSPC even though there was indeed free space.Why does this need to be run?What does the balance actually do?
ENOSPC: Why is `btrfs balance` required? What does it do?
btrfs
Unlike most conventional filesystems, BTRFS uses a two-stage allocator.  The first stage allocates large regions of space known as chunks for specific types of data, then the second stage allocates blocks like a regular filesystem within these larger regions.  There are three different types of chunks:Data Chunks: These store regular file data.Metadata Chunks: These store metadata about files, including among other things timestamps, checksums, file names, ownership, permissions, and extended attributes.System Chunks: These are a special type of chunk which stores data about where all the other chunks are located.Only the type of data that the chunk is allocated for can be stored in that chunk.  The most common case these days when you get a -ENOSPC error on BTRFS is that the filesystem has run out of room for data or metadata in existing chunks, and can't allocate a new chunk.  You can verify that this is the case by running btrfs fi df on the filesystem that threw the error.  If the Data or Metadata line shows a Total value that is significantly different from the Used value, then this is probably the cause.What btrfs balance does is to send things back through the allocator, which results in space usage in the chunks being compacted.  For example, if you have two metadata chunks that are both 40% full, a balance will result in them becoming one metadata chunk that's 80% full.  By compacting space usage like this, the balance operation is then able to delete the now empty chunks, and thus frees up room for the allocation of new chunks.  If you again run btrfs fi df after you run the balance, you should see that the Total and Used values are much closer to each other, since balance deleted chunks that weren't needed anymore.