overlay mount delegation not supported by this delegate

Error message

overlay mount delegation not supported by this delegate

What it means

mount_overlay is a trait method with a default implementation that always errors, so btrfs-only WorktreeDelegate implementations still compile. Calling overlay worktree mounting on a delegate that doesn't support it (e.g. a btrfs-snapshot delegate lacking CAP_SYS_ADMIN-based overlay mounting) hits this bail.

Source

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

    /// 4. Clean up stale git state (lock files, worktree registrations)
    fn create_snapshot(&self, source: &Path, dest: &Path) -> Result<DelegateSnapshotResult>;

    /// Delete a btrfs snapshot worktree.
    ///
    /// If `worktree_path` is a bind mount, the implementation should unmount it,
    /// delete the btrfs snapshot, and clean up the mount point.
    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.
    ///

View on GitHub (pinned to bc7f02eddd)

Solutions

Select/configure a delegate that supports overlay mounting (one that overrides mount_overlay, typically requiring CAP_SYS_ADMIN)
Switch the worktree mode to the delegate's supported strategy (e.g. btrfs snapshots)
Implement mount_overlay in your custom delegate if you own the trait impl
Verify the environment (kernel/privileges) supports the delegate you picked

Example fix

// before
let delegate = BtrfsDelegate::new();
delegate.mount_overlay(&lower, &upper, &work, &target)?;
// after
let delegate = OverlayDelegate::new(); // supports mount_overlay
delegate.mount_overlay(&lower, &upper, &work, &target)?;

Defensive patterns

Strategy: fallback

Validate before calling

fn delegate_supports_overlay(d: &dyn WorktreeDelegate) -> bool {
    d.supports_overlay() // expose a capability probe; default false for btrfs-only delegates
}

Try / catch

let result = match delegate_supports_overlay(delegate) {
    true => delegate.mount_overlay(&lower, &upper, &work, &target),
    false => delegate.snapshot_worktree(&target) // fallback strategy
        .map_err(|e| e.context("overlay unsupported; snapshot fallback failed")),
};

Prevention

Probe delegate capabilities before choosing an overlay-based workflow
Configure the delegate backend to match your worktree mode (overlay vs btrfs snapshot)
Ensure CAP_SYS_ADMIN/privileges when a delegate needs to mount overlays
Document required delegate features next to custom impls

When it happens

Trigger: Invoking an overlay-based worktree operation against a delegate whose type only implements the btrfs snapshot path and does not override mount_overlay.

Common situations: Configuring the tool to use a btrfs delegate but requesting overlay worktrees; running on a filesystem/kernel where the chosen delegate can't mount overlays; switching delegate backends without updating worktree mode.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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