I just broke my ZFS pool today. It wasn’t from the fact that I was running out of space and had earlier in the week just added a 5th drive to my 4 drive raidz1 pool, so this knowledge was fresh. Nor was it from the fact that I was going to be gone for the weekend and I wanted to get it done before I left. Neither was it from me not being able to sleep well this night and woke up at 1:30 in the morning and said, “I can’t sleep so lets add that 6th drive to the pool today.”

No, it was from not knowing the difference between ZFS’ zpool add and attach commands and how they are in fact two very different commands. Debian 13’s man page describes these commands as the following:

zpool-attach(8)/zpool-detach(8)
	Converts a non-redundant disk into a mirror,  or  increases  the  redundancy
    level  of  an  existing mirror (attach), or performs the inverse operation (
    detach).

zpool-add(8)/zpool-remove(8)
    Adds the specified virtual devices to the given pool, or removes the  speci‐
    fied device from the pool.

In layman terms, the attach command is for growing a vdev’s drive count. A vdev is the name for the virtual device or in my case raidz1-0. This can also be mirror-0 and or raidz2-0 and so on. For each additional vdev in the pool it will be incremental to raidz1-1 for example. zpool attach will not add additional vdevs but will add more drives to that vdev allowing for larger space usage via the expand zfs option found in zfs 2.3 and later. My pool which was 4 HDDs of 6TBs was running low at about 1.7TB left of space when migrating from one failing pool to this one. And by adding a 5th 6TB HDD allowed me to finish the last bit to get off that failing pool. Once finished I had 1.4TB left on the new 5 drive pool called tank. Keep your mind on this as I will get back to it soon.

After knowing the vdev situation and how that works, then picturing how zpool add functions is by adding a second vdev to the pool. If its a single drive like in my case since I though it would “add” this drive to the pool it will create a second vdev with the /dev/disk/by-id name as the vdev.

My pool tank looked like this before:

 pool: tank
 state: ONLINE
  scan: scrub repaired 0B in 07:42:18 with 0 errors on Sun Oct 11 08:06:19 2026
config:

	NAME                                 STATE     READ WRITE CKSUM
	tank                                 ONLINE       0     0     0
	  raidz1-0                           ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14A7K2  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14B3M9  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14C1P5  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14D8R4  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14E2T7  ONLINE       0     0     0

errors: No known data errors

And after:

  pool: tank
 state: ONLINE
  scan: scrub repaired 0B in 07:42:18 with 0 errors on Sun Oct 11 08:06:19 2026
config:

	NAME                                 STATE     READ WRITE CKSUM
	tank                                 ONLINE       0     0     0
	  raidz1-0                           ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14A7K2  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14B3M9  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14C1P5  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14D8R4  ONLINE       0     0     0
	    ata-ST6000VN001-2BB186_ZR14E2T7  ONLINE       0     0     0
	  ata-ST6000VN001-2BB186_ZR14F5W1    ONLINE       0     0     0

errors: No known data errors

Notice the last drive is in the same column as raidz1-0. That is how I knew something was off and after researching how to fix this, basically it boils down to you cant. You have to rebuild this pool from scratch or you can add a second drive to the new vdev and make it a mirror then remove it and then “attach” the drive to the raidz1-0 vdev. This is very bad though as this current setup means that if the new vdev/6th drive dies the entire pool is lost and the inverse is true too, if two drives in the raidz1-0 vdev die then the pool is lost too. So zpool add has its place in usefulness but this does no me no good at this point.

Please learn from my failure and learn what a vdev means and how zpool add and zpool attach work.

Given all of this, I did learn some very important things and can now better follow what a vdev actually is now whereas before I thought a vdev was not a nessesary thing and more like a Proxmox built thing that wasn’t part of the main ZFS. You may have already known this but its amazing that you can use a system for years like ZFS and still learn some basic things.