Troubleshooting

Relevant source files

• Dockerfile
• README.md

This page provides diagnostic procedures and solutions for common issues encountered when using sshfs-mac-docker. It covers platform-specific problems, connection failures, mount/unmount errors, and permission issues. For detailed configuration reference, see Configuration Reference. For basic usage instructions, see Getting Started.

Common Issues Overview

The following decision tree maps symptoms to their most likely causes and solutions:

Sources : README.md9 README.md:57-85 README.md:48-53

graph TD
    Start["Issue Encountered"]
Start --> BuildRun{"Container\nbuild or run\nissue?"}
Start --> Connect{"Cannot\nconnect from\nmacOS?"}
Start --> Mount{"SSHFS mount\nissue?"}
Start --> Unmount{"Cannot\nunmount?"}
BuildRun --> BuildFail["Build fails"]
BuildRun --> RunFail["Run fails"]
BuildFail --> CheckDocker["Check Docker/OrbStack\ninstallation"]
RunFail --> CheckPrivileged["Missing --privileged flag?"]
RunFail --> PortConflict["Ports 139/445 in use?"]
Connect --> LocalhostFail["Using localhost?"]
Connect --> IPWrong["Wrong container IP?"]
Connect --> GuestFail["Guest auth fails?"]
LocalhostFail --> UseContainerIP["Use container IP instead\ndocker inspect --format"]
IPWrong --> InspectContainer["Run docker inspect\nto get correct IP"]
GuestFail --> CheckSmb["Check smb.conf\nguest ok = yes"]
Mount --> SSHFail["SSH auth fails?"]
Mount --> PermFail["Read-only mount?"]
Mount --> NoAccess["Samba can't access?"]
SSHFail --> SSHCreds["Check SSH credentials\nand key-based auth"]
PermFail --> AddUID["Add uid=1000,gid=1000\nto sshfs options"]
NoAccess --> AddAllowOther["Add allow_other\nto sshfs options"]
Unmount --> BusyError["Device or resource\nbusy error?"]
BusyError --> UnmountFinder["Unmount from macOS Finder first\nthen fusermount -u"]
style Start fill:#f9f9f9
    style BusyError fill:#ffe6e6
    style LocalhostFail fill:#ffe6e6
    style PermFail fill:#ffe6e6

Platform-Specific Issues

OrbStack vs Docker Desktop

The system has different behavior depending on the Docker runtime:

Sources : README.md9

Docker Desktop Network Configuration

When using Docker Desktop on macOS, the default network configuration prevents SMB connections from macOS host to containers. This is because Docker Desktop uses a VM-based networking model that doesn't properly bridge SMB/CIFS ports.

Problem : Connecting to smb://172.17.0.2 (container IP) fails with connection timeout.

Solution Options :

1. Switch to OrbStack (recommended):

2. Modify Docker Desktop networking (advanced):

   • Requires changes to Docker Desktop's VM network routing
   • Not covered in this documentation due to complexity
   • Consider OrbStack instead

Diagnostic Command :

Sources : README.md9

Connection Problems

Localhost Limitation

The most common connection issue stems from attempting to use localhost or 127.0.0.1 to connect to the Samba share from macOS Finder.

Symptom : Connection to smb://localhost or smb://127.0.0.1 fails even though ports are forwarded.

Root Cause : While ports 139 and 445 are forwarded to localhost in the docker run command README.md31 macOS's SMB client doesn't properly recognize these forwarded ports. The connection must use the container's internal Docker network IP.

Solution :

sequenceDiagram
    participant User
    participant Terminal
    participant Docker
    participant Finder
    
    User->>Terminal: docker inspect --format '{{ .NetworkSettings.IPAddress }}' docker-sshfs
    Terminal->>Docker: Inspect container network
    Docker-->>Terminal: 172.17.0.2
    Terminal-->>User: Display IP
    
    User->>Finder: Connect to Server
    User->>Finder: smb://172.17.0.2
    
    rect rgb(240, 240, 240)
        Note over User,Finder: ❌ DO NOT use smb://localhost\n❌ DO NOT use smb://127.0.0.1\n✅ DO use container IP
    end
    
    Finder->>Docker: SMB connection to container IP
    Docker-->>Finder: Connection successful

Correct Workflow :

1. Get container IP:

2. Use the returned IP (e.g., 172.17.0.2) in Finder:

   smb://172.17.0.2
   

3. Connect as Guest when prompted

Sources : README.md:57-68

Container IP Discovery

If the container IP is not showing or returns empty:

Dynamic IP Detection Script :

Sources : README.md:57-61

Guest Authentication Issues

The Samba share is configured for guest access in smb.conf

Expected Behavior : When connecting via Finder, select "Connect as Guest" option.

Common Problems :

1. "Guest" option not appearing :

   • Verify smb.conf contains guest ok = yes smb.conf
   • Container may need rebuild if configuration changed

2. Guest connection rejected :

   • Check that smbd process is running inside container:

   • Verify ports are exposed:

3. Prompted for username/password :

   • Still use Guest option (ignore prompt)
   • Or use: username=sshuser, password=sshpass Dockerfile9

Sources : README.md67 Dockerfile9

Mount and Unmount Issues

Device or Resource Busy Error

This is the most common unmounting issue.

Symptom :

Root Cause : macOS Finder still has an active SMB connection to the Samba share, which is serving files from /samba-share. The symbolic link at /samba-share/remote points to /remote (the SSHFS mount point) Dockerfile30 While the SMB connection is active, the FUSE filesystem cannot be unmounted.

Solution Sequence :

1. Unmount from macOS Finder :

   • Open Finder
   • Locate the mounted share in sidebar or "Network" section
   • Click eject button or right-click → "Eject"

2. Unmount SSHFS inside container :

Alternative (Force Method) :

Sources : README.md:72-85 Dockerfile30

Write Permission Issues

Symptom : Files appear in Finder but are read-only, or write operations fail silently.

Root Cause : SSHFS mount missing uid=1000,gid=1000 options README.md53

Diagnostic :

Correct Mount Command :

Why These Options Matter :

Verification After Remounting :

Sources : README.md:48-53 Dockerfile9

Samba Cannot Access SSHFS Mount

Symptom : Samba share appears empty in Finder even after SSHFS mount succeeds.

Root Cause : Missing allow_other option in SSHFS mount, and/or user_allow_other not enabled in /etc/fuse.conf.

The Permission Chain :

Configuration Check :

1. Verify /etc/fuse.conf contains user_allow_other Dockerfile24:

2. Verify mount command includes allow_other README.md49:

Fix :

Sources : README.md:48-52 Dockerfile24

SSHFS Authentication Problems

SSH Connection Failures

Symptom : sshfs command hangs or fails with authentication error.

Common Causes :

SSH Key-Based Authentication :

Password Authentication :

Debug SSH Connection :

Sources : README.md:46-49

Container Runtime Issues

Privileged Mode Requirement

Symptom : Container starts but SSHFS mount fails with "Operation not permitted" or "fuse: device not found".

Root Cause : Missing --privileged flag when starting container README.md31

Why Privileged Is Required : FUSE (Filesystem in Userspace) requires access to /dev/fuse device and capability to perform mount operations. Standard containers lack these permissions.

Correct Run Command :

Verification :

Sources : README.md31

Port Conflicts

Symptom : Container fails to start with error about port binding:

Error starting userland proxy: listen tcp4 127.0.0.1:445: bind: address already in use

Cause : Ports 139 or 445 already in use on macOS host.

Check What's Using Ports :

Solutions :

1. Stop conflicting service :

2. Use different host ports (requires client-side port specification):

Sources : README.md31 Dockerfile27

Diagnostic Commands Reference

Container Status Checks

Filesystem and Mount Checks

Network Diagnostics

Configuration Verification

Sources : README.md:57-85 Dockerfile:1-34

Recovery Procedures

Complete Reset

If issues persist and the system is in an unknown state:

Log Collection for Bug Reports

Sources : README.md:1-90 Dockerfile:1-34