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 destination does not hold the snapshot your incremental stream starts from. An incremental stream is only the difference between two snapshots, so it can be applied only on top of an identical copy of the first one. Work out which snapshots both sides really share, then resend from the newest shared one. Do not reach for -F until you have read what it will destroy.
What the error means
The full message has two parts. The prefix is "cannot receive incremental stream" and the reason is "most recent snapshot of <filesystem> does not match incremental source", written across two lines in the OpenZFS source. The zfs-receive(8) man page states the rule: "If an incremental stream is received, then the destination file system must already exist, and its most recent snapshot must match the incremental stream's source."
"Match" means more than the same name. The stream records the globally unique ID (GUID) of the snapshot it starts from. In the receive code of zfs-2.4.4, the kernel walks back through the snapshots of the destination file system looking for one whose GUID equals that value. If it finds none, the receive fails with the message above. The zfsprops(7) page explains why GUIDs are the right test: a snapshot sent to another pool keeps the same GUID, so "the guid is suitable to identify a snapshot across pools". The same page says the GUID "does not change over its entire lifetime". It does not say what happens to a snapshot destroyed and created again under the same name; that is a new snapshot, and it is reasonable to expect a different GUID, but the man pages do not state it.
A neighbouring error is easy to confuse with this one: "destination <filesystem> has been modified since most recent snapshot". There the starting snapshot is present, but the destination file system has changed since it, and the receive will not overwrite those changes unless forced. In the zfs-2.4.4 receive code, a starting snapshot that is found further back in the destination's history, with newer snapshots after it, also gives this "modified" message. The title message appears when the starting snapshot's GUID is not in the destination's history at all.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
| The starting snapshot was never received, for example a night's transfer failed after the sender had already taken the next snapshot | The job names a base snapshot the destination does not list | List snapshots on both sides and compare names and GUIDs |
| The destination's pruning removed the snapshot the next stream starts from | The destination's newest snapshot is older than the sender expects | Compare the destination's snapshot list with the sender's retention rules |
| A snapshot with the same name but a different GUID | Names match on both sides, but the error persists | Compare the guid column, not the names |
| The destination was built another way, such as a file copy followed by a snapshot, or a second full send into a different dataset | No snapshot on the destination has a GUID that exists on the source | No GUID is common to both lists |
| The wrong destination dataset is named in the receive command | The destination lists a different history than expected | Check the dataset name in the job against the one you inspected |
| Destination changed since its newest snapshot | The other message: "has been modified since most recent snapshot" | Look at what wrote to the destination, such as a mount that is read-write |
Prove the cause before changing anything
These commands only read.
On the source and on the destination, list snapshots with their GUIDs, oldest first. The man page for zfs list shows -t type, -o property and -s property:
zfs list -r -t snapshot -o name,guid,creation -s creation tank/data
zfs list -r -t snapshot -o name,guid,creation -s creation backup/data
On the source, find the newest GUID that also appears on the destination. That snapshot is your common snapshot. A good result is that the destination's newest snapshot has the same GUID as one on the source. A bad result is no shared GUID. A shared GUID that is not the newest on the destination means the destination has newer snapshots of its own; per the zfs-2.4.4 receive code, that case gives the "has been modified since most recent snapshot" message, not the title message.
To see what an incremental from the common snapshot would send, without sending anything, use the dry-run flags documented in zfs-send(8):
zfs send -n -v -i @d2 tank/data@d4
-n does a dry run and -v prints what would be sent. The man page notes that with -n the verbose output is written to standard output.
If the destination had a failed transfer, check whether it holds a partial receive. The man page says zfs receive -s saves partial state, and the file system then has a receive_resume_token property, from which zfs send -t <token> can resume. A resumable receive left over is a different situation: finish or abort it first (zfs receive -A <filesystem> aborts and deletes the partial state).
Disruptive step: aborting deletes the partial state, so the transfer has to start again from the beginning. There is no way back.
Fix
A common snapshot exists. Send from it to the newest source snapshot. A single -i stream may skip snapshots in between:
zfs send -i @d2 tank/data@d4 | ssh backup01 zfs receive backup/data
If you want the destination to carry the intermediate snapshots as well, the -I form sends all of them ("-I @a fs@d is similar to -i @a fs@b; -i @b fs@c; -i @c fs@d").
If the destination has newer snapshots of its own than the common one, or has changed since it, the receive refuses with the "has been modified since most recent snapshot" message. Adding -F is the cure for that message. It does not resolve the title message: when no snapshot GUID is shared, the fix is a common snapshot or a new full send, as below.
Disruptive step: zfs receive -F rolls the destination back before the receive. The man page words it as: "Force a rollback of the file system to the most recent snapshot before performing the receive operation." The reading below that the rollback goes to the common snapshot, and destroys newer ones, comes from the zfs-2.4.4 source, not from the man page. In the receive code, in force mode the snapshots on the destination that are newer than the starting snapshot are destroyed, and changes made since it are discarded. With a replication stream (zfs send -R), snapshots and file systems that do not exist on the sender are also destroyed. There is no way back from the destination itself. Only use it after you have listed those newer snapshots and are sure they are not the only copy of anything. Start with zfs receive -n -v, which the man page says does not receive but prints the name the receive would use.
No common snapshot. An incremental cannot work. A full send is needed. The safest way is to receive into a name that does not exist yet:
zfs send tank/data@d4 | ssh backup01 zfs receive backup/data-new
A full stream creates a new file system, so nothing existing is touched. Once you have checked it, change the job to use the new dataset. The code refuses to receive a full stream into an existing file system unless forced ("destination already exists"), and forcing it replaces that file system.
Disruptive step: zfs receive -F of a full stream onto an existing dataset overwrites it. The old destination history is lost with it, and there is no way back.
Same name, different GUID. Treat it as no common snapshot unless an earlier snapshot has a matching GUID. Look for older snapshots in the list first: the newest GUID that appears on both sides is the one to use, even if it is several days old.
Raw (encrypted) streams. The zfs-receive(8) page describes a separate failure, "IV set guid mismatch", for a raw incremental received on top of a non-raw receive. Its documented remedy is to roll the destination back to the most recent snapshot received raw and take the raw incremental from there, or to receive a new full raw stream.
Disruptive step: rolling the destination back to an earlier snapshot destroys the snapshots made after it there (zfs rollback -r). They cannot be recovered on the destination, so first confirm that the sender still holds every snapshot you need.
Preventing it. Keep the last sent snapshot on the sender until the destination has it. zfs hold adds a named tag to a snapshot, and attempts to destroy a held snapshot fail. A bookmark (zfs bookmark) marks the point in time of a snapshot, can be used as the incremental source for zfs send. Pruning on the destination must always leave the snapshot the next run starts from.
Example (illustrative): tank/data on fs01 is sent nightly to backup/data on backup01. Snapshots d1 to d4 exist on the source. The d3 transfer failed, so the destination holds d1 and d2 only. The job still sends -i @d3 tank/data@d4 and fails. The GUID lists show source d2 as 1111, d3 as 2222 and d4 as 3333, and the destination d2 as 1111. The common snapshot is d2. Daily change is about 6 GiB, so zfs send -i @d2 tank/data@d4 carries at most 6 + 6 = 12 GiB (less if the same blocks changed twice), where a full resend of the 800 GiB dataset would move 800 GiB.
Confirm the fix
zfs receivereturns without an error and the destination's newest snapshot now has the same GUID as the newest source snapshot.- The following night's run succeeds with its normal incremental, without any change.
- The destination file system reads correctly. Mount it read-only or open a few files and compare them with the source at the same snapshot. A checksum of a sample is a stronger check than a successful exit code.
- Nothing you depend on was destroyed: compare the destination's snapshot list before and after against what you expected.
What to watch afterwards
- The exit status and the last line of the job's output every night. Alert on any non-zero status instead of reading logs by hand.
- The age of the newest snapshot on the destination. If it is more than one cycle old, the job has been failing quietly.
- Holds or bookmarks on the sender, so a pruning job cannot remove the next base.
- Anything that writes to the destination. If the destination exists only to receive,
readonly=on(thezfsprops(7)page lists it, with defaultoff) stops local changes that would trigger the "has been modified" error.
Read next
Related articles you may want next.
- Backup & RecoveryImporting a ZFS pool on replacement hardware: hostid, cache files and feature flag compatibilityHow to plan importing a ZFS pool on a replacement server: export and active pools, the cache file, hostid, multihost, feature flags and read-only import.Read article
- Backup & RecoveryBtrfs snapshots are not backups: send and receive, and recovering a filesystem that will not mountWhy Btrfs snapshots are not backups, how send and receive copy them elsewhere, and the cautious, documented steps when a Btrfs filesystem will not mount.Read article
- Backup & RecoveryFinding a bad backup before the day you need itWhat hashes, signatures and sample restores detect in backups, which faults they miss, and when to treat a copy as unusable.Read article
Risks and limits
- The checks and messages come from OpenZFS source tag zfs-2.4.4 and the master man pages. Older releases and other implementations may word messages differently.
- The man pages do not say whether a dry-run receive (
-n) catches a mismatch before data is sent. Do not rely on it for that. -Fand forced full receives destroy data on the destination. Without another copy there is no recovery.- A matching GUID shows the snapshot is the same snapshot. It does not prove the data on the destination is intact; only a scrub and a restore test do that.
- These commands have not been run or lab-tested.
Sources
- zfs-receive(8), OpenZFS documentation (master, page footer 2026) — OpenZFS project, copyright 2026, accessed 17 November 2026
- zfs-send(8), OpenZFS documentation (master) — OpenZFS project, date not shown, accessed 17 November 2026
- zfs-list(8), OpenZFS documentation (master) — OpenZFS project, date not shown, accessed 17 November 2026
- zfs-hold(8), OpenZFS documentation (master) — OpenZFS project, date not shown, accessed 17 November 2026
- zfs-bookmark(8), OpenZFS documentation (master) — OpenZFS project, date not shown, accessed 17 November 2026
- zfsprops(7), OpenZFS documentation (master) — OpenZFS project, date not shown, accessed 17 November 2026
- OpenZFS source, lib/libzfs/libzfs_sendrecv.c at tag zfs-2.4.4 — OpenZFS project, tag zfs-2.4.4, release dated 2026-08-21, accessed 17 November 2026
- OpenZFS source, module/zfs/dmu_recv.c at tag zfs-2.4.4 — OpenZFS project, tag zfs-2.4.4, release dated 2026-08-21, accessed 17 November 2026
This article was originally published on .