Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

XFS 'Filesystem has duplicate UUID ... can't mount' on a snapshot or restored disk

Technical article
Backup & Recovery

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

The kernel refuses to mount an XFS filesystem if another mounted XFS filesystem already has the same UUID. A snapshot, clone or restored disk is a byte-for-byte copy, so it carries its original's UUID. Attach it to a machine that still has the original mounted and the second mount fails.

You have two clean ways out. For a look at the data, mount the copy with the nouuid option (and, for a read-only look, norecovery). To keep the copy attached long term, give it its own UUID while it is unmounted. Neither is free of risk, covered below.

What the error means

In mainline Linux, xfs_uuid_mount() in fs/xfs/xfs_mount.c has the comment "See if the UUID is unique among mounted XFS filesystems. Mount fails if UUID is nil or a FS with the same UUID is already mounted." On a clash it logs Filesystem has duplicate UUID %pU - can't mount and returns -EINVAL (xfs_mount.c). If the nouuid option is set, the function returns before the check. A filesystem with an all-zero UUID gets a separate message, Filesystem has null UUID - can't mount.

The check compares only filesystems that are mounted at the same time. The same disk image mounted alone, or the original unmounted, does not clash. That is why the fault appears in recovery work: a restore test attached next to the live system, a hypervisor snapshot presented to a helper VM, or an LVM snapshot beside its origin.

The xfs(5) man page describes the two options involved:

  • nouuid: "Don't check for double mounted file systems using the file system uuid." It adds: "This is useful to mount LVM snapshot volumes, and often used in combination with norecovery for mounting read-only snapshots."
  • norecovery: "The filesystem will be mounted without running log recovery." and "Filesystems mounted norecovery must be mounted read-only or the mount will fail."

The kernel administration guide adds a caution: "If the filesystem was not cleanly unmounted, it is likely to be inconsistent when mounted in norecovery mode."

The same man page warns about duplicates generally: with two XFS filesystems of the same UUID on one machine, xfsdump "may become confused when doing incremental and resumed dumps", and it advises you to "avoid using dd(1) or other block-by-block copying programs to copy XFS filesystems".

Likely causes

Cause What you see How to confirm
Restored or cloned disk attached beside the original Mount of the copy fails with the duplicate-UUID message Two devices show the same UUID in lsblk -o +UUID,PARTUUID
LVM or hypervisor snapshot presented to the same host Same, on the snapshot volume Snapshot's UUID equals the origin's; origin is mounted
Block-level copy (dd or similar) of a filesystem Same; tools report two identical UUIDs Same UUID on source and target
UUID-based fstab or mount entry now ambiguous Wrong device mounted, or a boot or mount failure after a disk was added lsblk UUID column; compare against fstab
Null UUID Message names a null UUID instead Message text differs from the duplicate message

Prove the cause before changing anything

These commands are taken from the documentation and have not been run. Everything in this section only reads.

lsblk -o +UUID,PARTUUID

The mount(8) page suggests this to check that UUIDs are unique, and states that "there is no guarantee that UUIDs and labels are really unique, especially if you move, share or copy the device."

Then confirm the kernel's complaint in the kernel log, looking for the text Filesystem has duplicate UUID.

If the copy is unmounted you can print its UUID with the xfs_admin query option, which only reads:

xfs_admin -u <device>

Finally, find out whether the copy's log is clean before you decide how to mount it. The xfs_repair(8) page describes -n as "No modify mode" and says the filesystem "must be unmounted", and that "xfs_repair cannot replay a dirty log and will exit with a status code of 2 when it detects a dirty log." So, on the unmounted copy:

xfs_repair -n <device>

An exit status of 2 means the log has not been replayed. A copy captured while the filesystem was in use, without a clean unmount, can look like this.

Example (illustrative): on FILE01, /dev/sdb1 is the live data volume mounted at /data. A restore test attaches a restored copy as /dev/sdc1. lsblk -o +UUID shows sdb1 and sdc1 both with the UUID 3f9a1c52-7b64-4d0e-9a11-0c2f6e8d5a77 (invented). mount /dev/sdc1 /mnt/restore fails, and the kernel log carries the duplicate-UUID line. xfs_repair -n /dev/sdc1 exits with 2.

Fix

To inspect or copy files out (most restore tests)

Mount the copy read-only, without the UUID check and without log recovery:

mount -t xfs -o ro,nouuid,norecovery /dev/sdc1 /mnt/restore

-o takes a comma-separated list (mount(8)), and -t names the filesystem type. Read the files you need, then unmount.

Limits: with norecovery and a dirty log, the view may be inconsistent (kernel guide). That is acceptable for spot checks but is not proof that a restore is good. A file that is missing or half-written in this view may be fine after recovery, and the reverse is possible.

When you need the copy's recovered state

To have the log replayed you must mount without norecovery. The xfs_repair page says "the log can be replayed by mounting and immediately unmounting the filesystem", and that if mounting fails, -L erases the log and "should only be used as a last resort."

Risky step: mounting without norecovery writes to the copy, and xfs_repair -L discards the log. Do this only on a disposable copy or a clone you can recreate, never on the only restored copy of data you cannot get again. Preserve the copy first (a second snapshot or image of the device). Do not reach for -L as a first move.

mount -t xfs -o nouuid /dev/sdc1 /mnt/restore
umount /mnt/restore

The xfsprogs source (db/sb.c) pairs these two steps itself. Its error for a dirty log reads "Mount the filesystem to replay the log, and unmount it before re-running" and adds "If the filesystem is a snapshot of a mounted filesystem, you may need to give mount the nouuid option." If the device itself is read-only, replay by mounting may not be possible, so work on a writable copy.

To keep the copy attached (give it a new UUID)

With the filesystem unmounted, xfs_admin -U sets a new UUID. The man page lists these values: a UUID you supply, generate (new random), nil (all zeros), and restore (back to the original). It also says "Administrators must unmount filesystems before xfs_admin or xfs_db can convert parameters."

xfs_admin -U generate <device>

Risky step. On filesystems with metadata checksums (CRC), changing the UUID will "set an incompatible flag such that older kernels will not be able to mount the filesystem". xfs_admin -U restore removes that flag by restoring the original UUID. Run it only on the copy, never on the production original, and note the change: anything that names the old UUID (a mount entry, a backup job selecting by UUID, a script) no longer matches. Setting a UUID needs a clean log: the xfsprogs source refuses on a dirty log with "The filesystem has valuable metadata changes in a log which needs to be replayed". Run xfs_repair -n first, and replay a dirty log as above (mount, then unmount) before running xfs_admin -U.

The ext4 equivalent, briefly

The documentation cited here does not say whether ext4 refuses a duplicate mount, so do not assume it does or does not. The identifier problem is the same: mount(8) warns that UUIDs may not be unique after a copy, and tune2fs(8) (E2fsprogs 1.47.4) sets a new one with tune2fs -U random <device> (also time, clear, or an explicit UUID). Its feature notes mention that changing the UUID of a filesystem using metadata_csum while mounted is a special case (metadata_csum_seed); change it unmounted.

Confirm the fix

  1. lsblk -o +UUID,PARTUUID shows the copy with a different UUID (if you changed it) or the original unchanged (if you used nouuid).
  2. The mount succeeds, and a file you know the content of opens and matches. Compare checksums of a sample against the source, not just a directory listing.
  3. For a restore test, the real proof is the application: start the service on the restored data or run its own consistency check, as a mounted directory listing does not show that the data is usable.

What to watch afterwards

  • If you use nouuid routinely, document it. It disables a safety check for that mount only; it does not change the disk.
  • If you changed a UUID, record the new one beside the old, and update every mount entry that names the copy.
  • Restore-test hosts should not mount a restored volume next to its source. Using a separate recovery VM avoids the clash. If a backup procedure mounts an LVM snapshot of an XFS volume beside its origin, build nouuid and a read-only mount into it; xfs(5) names this as the use case.
  • Recurrence signal: the same kernel message after every restore test means the procedure, not the disk, needs changing.

Risks and limits

  • These commands have not been run or lab-tested. They are taken from the man pages and kernel source named below.
  • The kernel message text is from mainline source as accessed; distribution kernels may differ in wording or patch level. Vendor documentation, such as Red Hat's, may add distribution-specific guidance.
  • The xfs_admin man page states no clean-log condition for -U; the requirement comes from the xfsprogs source.
  • Hypervisor and cloud snapshot tooling may present disks in ways that differ from LVM; the pages cited here do not cover them.

Sources

  • xfs(5) mount options (nouuid, norecovery, duplicate UUIDs) — man7.org, obtained from upstream 2026-08-04, rendered 2026-09-09, accessed 16 November 2026
  • xfs_admin(8) — man7.org, obtained from upstream 2026-08-04, rendered 2026-09-09, accessed 16 November 2026
  • xfs_repair(8) — man7.org, obtained from upstream 2026-08-04, rendered 2026-09-09, accessed 16 November 2026
  • mount(8) — man7.org, date not shown (describes util-linux 2.41 or later), accessed 16 November 2026
  • tune2fs(8) — man7.org, E2fsprogs 1.47.4, March 2025, accessed 16 November 2026
  • XFS administration guide — kernel.org, page version 7.4.0-rc3, date not shown, accessed 16 November 2026
  • fs/xfs/xfs_mount.c — Linux kernel source (GitHub mirror), master branch as accessed, accessed 16 November 2026
  • xfsprogs db/sb.c — xfsprogs source (kernel.org), master branch as accessed, accessed 16 November 2026