Technology · PRACTICAL GUIDE
Linux says “Invalid cross-device link”? Prove the mount boundary before choosing rename, copy, or publish
EXDEV is a contract warning, not a path-string puzzle. Map both paths in the caller’s mount namespace, decide whether atomic rename is required, then stage and verify any cross-filesystem copy before deleting the source.
Linux returns EXDEV—often rendered as “Invalid cross-device link”—when rename cannot perform the requested move within one mounted filesystem. The directory names may look related, yet bind mounts, container volumes, tmpfs, overlay layers, and separate filesystems can put the source and destination on different mount identities. Inspect the paths from the same mount namespace as the failing process before changing code or permissions.
A cross-filesystem fallback is not a disguised rename. It is a copy followed by validation and, only after success, source removal. If readers must never observe a partial destination, write a temporary object on the destination filesystem, flush and verify it, then rename that temporary object to the final name locally. Preserve only the metadata your tool and destination actually support, and state plainly that the whole move is not atomic across mounts.
1. Capture the failing operation and its namespace
Record the exact source, destination, process identity, container or service context, and the error returned by the real caller. Do not reproduce only from a host shell if the failure occurs inside a container or private mount namespace: the same path string can resolve to a different mount table.
Also record whether the requested action is a simple relocation, a replacement of an existing name, or a publication step that promises readers an all-or-nothing result. That requirement determines whether copy-and-delete is acceptable.
2. Map both paths to mount identities
Run findmnt --target against the source and the destination directory from the caller’s namespace. When investigating another process, use findmnt --task PID or inspect /proc/PID/mountinfo with appropriate permission. Compare mount IDs, roots, mount points, filesystem types, and sources instead of relying on directory prefixes.
Resolve the destination parent when the final file does not yet exist. A bind mount can show the same underlying device with a different mount identity, and Linux rename(2) documents that the kernel may reject a rename across mounted filesystems even when one filesystem is mounted at both locations.
3. Decide which guarantee the operation needs
If the operation must be one atomic namespace change, keep the temporary and final names on the same mount and use rename there. Reconfigure the temporary directory, workspace, volume, or publication staging path rather than adding a blind cross-filesystem copy.
If temporary duplication and a non-atomic overall move are acceptable, a copy workflow can be correct—but its guarantees must be explicit. Treat the source as authoritative until the destination has passed verification.
4. Stage and verify on the destination filesystem
Create a unique temporary name in the destination directory, copy the data, close and flush it as required by the durability policy, then verify size or a cryptographic digest. Check the metadata the application depends on: mode, owner, timestamps, ACLs, extended attributes, symlink identity, and sparse allocation do not all survive every copy method.
After verification, rename the destination-side temporary object to the final name. That last rename can be atomic because both names are on one mount. Confirm the final object and its access policy before deleting the original.
5. Test failure boundaries instead of hiding EXDEV
Exercise interruption before copy completion, after verification, after the local destination rename, and before source deletion. The recovery procedure should identify and safely handle a leftover temporary destination, a complete final destination plus an undeleted source, and a retry after a process crash.
Do not “fix” EXDEV by changing permissions, retrying the same rename, or suppressing the error. Preserve it as evidence that the requested atomic contract crosses a mount boundary, then choose a workflow whose weaker and stronger guarantees are documented.
