overlay unmount delegation not supported by this delegate

Error message

overlay unmount delegation not supported by this delegate

What it means

This error comes from the default delegate implementation of `unmount_overlay`, which is a stub: it discards the target path and immediately fails. Overlay worktree mounting is only supported by delegates that implement namespace-based unmount; this one explicitly does not. It indicates the caller asked a delegate to undo a `mount_overlay` operation it cannot perform.

Source

Thrown at crates/codegen/xai-fast-worktree/src/api.rs:85

    fn delete_snapshot(&self, worktree_path: &Path) -> Result<RemoveReport>;

    /// Mount an overlayfs at `target` in the *caller's* mount namespace.
    ///
    /// A FUSE+overlay worktree needs a new overlay mount, which a rootless
    /// caller can't do (no `CAP_SYS_ADMIN`); the privileged delegate mounts it
    /// inside the caller's namespace (an overlay mount can't be exposed via a
    /// namespace-crossing symlink the way a btrfs snapshot can). Default impl
    /// errors so btrfs-only delegates still compile.
    fn mount_overlay(&self, lower: &Path, upper: &Path, work: &Path, target: &Path) -> Result<()> {
        let _ = (lower, upper, work, target);
        anyhow::bail!("overlay mount delegation not supported by this delegate")
    }

    /// Unmount an overlay worktree previously mounted via [`Self::mount_overlay`]
    /// (in the caller's mount namespace).
    fn unmount_overlay(&self, target: &Path) -> Result<()> {
        let _ = target;
        anyhow::bail!("overlay unmount delegation not supported by this delegate")
    }
}

/// How to treat the source working tree when creating the destination worktree.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub enum WorkingTreeMode {
    /// Replicate the working tree exactly as-is (including local modifications and untracked files).
    #[default]
    PreserveWorkingTree,
    /// Produce a clean checked-out working tree for tracked files.
    ///
    /// Local modifications and untracked files from the source are not copied.
    CleanTracked,
    /// Produce a clean worktree and also remove any untracked files (equivalent to
    /// `git reset --hard` + `git clean -fd`).
    ///
    /// Note: ignored files are not removed by default `git clean`.
    CleanAll,

View on GitHub (pinned to bc7f02eddd)

Solutions

Check whether the concrete delegate type overrides `unmount_overlay`; if not, it cannot unmount overlays.
If you mounted the overlay, unmount it yourself with the matching mechanism, e.g. run `umount <target>` (or `fusermount -u`) in the mount namespace where it was mounted.
Guard the cleanup path: only call `unmount_overlay` when the delegate advertises unmount support, or treat this specific error as a no-op.
Upgrade/switch to a delegate implementation that supports overlay unmount delegation.
Release/delete the destination worktree directory manually once unmounted, since the library will not clean it up.

Example fix

// before
let delegate = DefaultDelegate::new();
delegate.unmount_overlay(&overlay_path)?; // bails: not supported
// after
// unmount in the mount namespace yourself
detach_mount(&overlay_path)?; // e.g. run `umount <target>` via Command in the owning namespace

Defensive patterns

Strategy: fallback

Validate before calling

// Only call when the delegate actually supports unmount.
fn supports_unmount(d: &dyn Delegate) -> bool {
    // e.g. feature-detect via a capability method or type check
    d.capabilities().overlay_unmount
}
if !supports_unmount(&delegate) { skip_unmount(); }

Type guard

fn supports_overlay_unmount(d: &dyn Delegate) -> bool {
    d.as_any().downcast_ref::<NamespaceDelegate>().is_some()
}

Try / catch

match delegate.unmount_overlay(&target) {
    Err(e) if e.to_string().contains("not supported") => {
        // fall back to manual umount in the owning namespace
        manual_umount(&target)?;
    }
    r => r?,
}

Prevention

Check delegate capabilities before mounting overlays you'll later need to unmount
Centralize mount/unmount pairs so both use the same delegate
Treat 'not supported' delegate errors as fallback triggers, not bugs
Run unmounts in the same mount namespace where the mount happened

When it happens

Trigger: Calling `unmount_overlay(target)` on a delegate whose `unmount_overlay` uses the default/trait-provided stub implementation instead of an overridden one (typically on platforms or delegate types that lack mount-namespace support).

Common situations: Running on Linux configurations where the delegate was constructed without overlay-unmount capability; calling cleanup/teardown paths that unconditionally try to unmount an overlay worktree; library version where only `mount_overlay` was implemented for the chosen delegate.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/8fe15af5f71c51b2. Report an issue: GitHub.