Device or Resource Busy Errors

Relevant source files

• README.md

Purpose and Scope

This page documents the "Device or resource busy" error that occurs when attempting to unmount SSHFS filesystems in the docker-sshfs container. This error manifests when the fusermount -u command fails due to active connections from macOS Finder to the Samba share. This page covers the root cause, resolution steps, and prevention strategies.

For general unmounting procedures and container cleanup, see Unmounting and Cleanup. For issues establishing the initial connection, see Connection Problems.

Sources: README.md:72-86

Error Description

When attempting to unmount an SSHFS filesystem using the fusermount command, you may encounter the following error:

This error indicates that the mount point at /samba-share cannot be unmounted because another process or service is actively using the filesystem.

Sources: README.md:79-83

Root Cause Analysis

The "Device or resource busy" error occurs due to the dependency chain between the macOS SMB client, the smbd daemon, and the FUSE mount point. The error reflects the following system state:

Dependency Chain

The system maintains the following dependency relationships:

Diagram: Dependency Chain Preventing Unmount

The error occurs because the Linux kernel's FUSE implementation prevents unmounting a filesystem that has active file descriptors or directory handles open. The smbd process maintains these handles as long as the macOS Finder client is connected to the SMB share.

Sources: README.md:79-86

System State During Error

When the unmount fails, the system is in the following state:

Diagram: System State Machine Showing Error Condition

The error occurs when attempting to transition from the macOSConnected state directly to the unmounted state without first disconnecting the macOS Finder client.

Sources: README.md:72-86

Resolution Procedure

Step 1: Disconnect macOS Finder from SMB Share

Before unmounting the SSHFS filesystem, you must first disconnect the macOS Finder client from the Samba share.

Method 1: Eject from Finder

1. Open macOS Finder
2. Locate the mounted network share in the sidebar under "Locations" or "Network"
3. Click the eject icon next to the share name

Method 2: Unmount from Terminal

Step 2: Verify Samba Connections Closed

After disconnecting from Finder, verify that smbd no longer has active connections:

Step 3: Unmount SSHFS Filesystem

Once the macOS client is disconnected, the unmount command should succeed:

If successful, no output is displayed and the command returns exit code 0.

Sources: README.md:72-86

sequenceDiagram
    participant User
    participant Finder as macOS Finder
    participant smbd as smbd Daemon
    participant FUSE as FUSE Layer
    participant MountPoint as /samba-share
    
    rect rgb(255, 240, 240)
        Note over User,MountPoint: Failed Unmount Sequence
        User->>FUSE: fusermount -u /samba-share
        FUSE->>MountPoint: Check for active handles
        MountPoint-->>FUSE: smbd has open file descriptors
        FUSE-->>User: Error: Device or resource busy
        Note over User: Mount still active
    end
    
    rect rgb(240, 255, 240)
        Note over User,MountPoint: Successful Unmount Sequence
        User->>Finder: Eject SMB share
        Finder->>smbd: Close SMB connection
        smbd->>FUSE: Release file descriptors
        FUSE->>MountPoint: All handles closed
        
        User->>FUSE: fusermount -u /samba-share
        FUSE->>MountPoint: Check for active handles
        MountPoint-->>FUSE: No open handles
        FUSE->>MountPoint: Unmount filesystem
        MountPoint-->>User: Success (exit code 0)
    end

Resolution Sequence Diagram

The following diagram illustrates the correct sequence for unmounting versus the failed sequence:

Diagram: Failed vs Successful Unmount Sequence

The key difference is that the successful sequence ensures all Samba connections are closed before attempting the unmount operation.

Sources: README.md:72-86

Troubleshooting Flowchart

Diagram: Troubleshooting Decision Tree

This flowchart provides a systematic approach to resolving the unmount error.

Sources: README.md:72-86

Prevention Strategies

Strategy 1: Establish Unmount Order Protocol

Always follow this order when disconnecting:

1. First: Unmount the SMB share from macOS Finder
2. Second: Verify Samba connections are closed (smbstatus --brief)
3. Third: Unmount the SSHFS filesystem (fusermount -u /samba-share)

Strategy 2: Monitor Active Connections

Before attempting unmount, check for active Samba sessions:

Strategy 3: Use Forced Unmount with Caution

If normal unmount fails and you've verified Finder is disconnected, you can attempt a lazy unmount:

The -z flag (lazy unmount) detaches the filesystem immediately but delays cleanup until all references are released. However, this can lead to inconsistent states and should only be used when normal unmount repeatedly fails.

Note: Lazy unmount may result in cached data not being flushed to the remote server. Use only as a last resort.

Sources: README.md:72-86

Alternative Solution: Container Stop

If unmounting proves difficult or if you need to disconnect immediately, stopping the container will force cleanup of all resources:

This approach:

• Terminates the smbd daemon (running as PID 1 in the container)
• Forces disconnection of all SMB clients
• Triggers automatic FUSE filesystem cleanup
• Closes the SSH connection to the remote server

Consequences of Container Stop

After stopping the container, you can restart it and remount the remote filesystem fresh:

Sources: README.md:72-86

Technical Details

FUSE Mount Reference Counting

The FUSE kernel module maintains a reference count for each mount point. The count increments when:

• A process opens a file or directory on the mount
• A process holds a file descriptor to the mount
• A process has a current working directory on the mount

The fusermount -u command can only succeed when the reference count reaches zero. The smbd daemon holds references for each active SMB client session.

Relevant File Paths

Related SSHFS Mount Options

The mount options specified during the initial sshfs command affect the unmount behavior:

• allow_other: Enables smbd (running as sshuser) to access the mount
• Without this option, only the mounting user could access files, preventing Samba integration

The allow_other option is critical for the system to function but also means multiple processes can hold references to the mount, increasing the likelihood of busy errors during unmount.

Sources: README.md:49-53 README.md:76-86

Summary

The "Device or resource busy" error when unmounting /samba-share is a normal consequence of the system's architecture where the smbd daemon maintains open file handles to serve macOS Finder clients. The error is resolved by disconnecting the SMB client first, then unmounting the FUSE filesystem. When in doubt, stopping the container provides a forceful but reliable cleanup method.

Sources: README.md:72-86