Troubleshooting FileRetrieval Issues with SSHFSSSHFS (SSH Filesystem) lets you mount a remote directory over SSH as if it were a local filesystem. It’s a simple, secure way to access remote files, but sometimes file retrieval fails or behaves unexpectedly. This article walks through common causes of SSHFS file-retrieval problems, step-by-step diagnostics, and practical fixes — from connection issues and permissions to performance tuning and caching pitfalls.
When to suspect a FileRetrieval problem
You may be experiencing file-retrieval issues with SSHFS if you see one or more of the following:
- Mounted filesystem appears but files are missing or cannot be opened.
- Operations hang (e.g., ls, cat, cp) or are extremely slow.
- I/O errors, input/output errors, or “stale file handle” messages.
- Permission denied errors for files that exist and are readable on the server.
- Unexpected EAGAIN, EIO, or transport errors in logs.
Basic checklist (quick fixes)
- Confirm SSH connectivity: run ssh user@host and verify you can list the directory you plan to mount.
- Check SSHFS and FUSE versions: ensure you’re running compatible, up-to-date software on both client and server.
- Verify mount command and options: confirm correct remote path, user, and options (uid/gid, allow_other, reconnect, etc.).
- Ensure proper user permissions on the server filesystem and that SSH keys or passwords are working.
Step-by-step diagnostics
- Reproduce and capture errors
- Try basic commands on the mount: ls -la, cat a small file, stat a file, and cp a file. Note exact error messages and timestamps.
- Check system logs on the client: journalctl -f or /var/log/syslog to capture fuse/sshfs messages.
- On the server, check /var/log/auth.log, /var/log/syslog, and the SSH daemon logs for connection drops or authentication issues.
- Test raw SSH access
- Run ssh -v user@host and attempt remote file operations with ssh user@host ls -la /path/to/dir. If SSH fails, fix SSH before debugging SSHFS.
- Validate mount options
- Common useful options:
- reconnect — tries to reconnect after network interruptions.
- ServerAliveInterval=15, ServerAliveCountMax=3 (via -o ssh_command=‘ssh -o ServerAliveInterval=15 -o ServerAliveCountMax=3’) to keep connections alive.
- allow_other — allows other local users to access the mount (requires user_allow_other in /etc/fuse.conf).
- uid, gid, umask — map file ownership/permissions for the client.
- workaround for permissions: use -o idmap=user or -o uid=1000,gid=1000.
- If you used custom SSH options in ssh_config, ensure sshfs is using them or pass via -o ssh_command=‘ssh -F /path/to/config’.
- Check file permissions and user mapping
- SSHFS maps server-side UIDs/GIDs to client ones. If user IDs differ, files may appear owned by a different user or be inaccessible.
- Use idmap=user to map remote user ownership to local user, or explicitly set uid/gid on mount.
- Confirm server filesystem ACLs or SELinux contexts are not blocking access.
- Diagnose “stale file handle” errors
- Stale file handles occur when the server-side inode changes (e.g., file replaced, NFS/remote rename). Remounting usually resolves this.
- If frequent, consider disabling aggressive caching (-o cache_timeout=0) or use -o kernel_cache to change caching behavior. Experiment with cache-related options:
- -o cache_timeout, -o attr_timeout, -o entry_timeout, -o negative_timeout.
- For heavy file churn, set low timeouts or use direct scp/rsync for bulk transfers.
- Handle hanging or very slow operations
- Check network latency and packet loss (ping, mtr).
- Enable compression (-C) if bandwidth-limited; disable if CPU-bound.
- Try -o defer_permissions or -o big_writes (note: big_writes requires kernel support).
- Use -o direct_io to bypass OS page cache for large sequential reads/writes.
- Monitor CPU and I/O on both client and server (top, iostat, vmstat); high CPU can indicate encryption overhead.
- Authentication and key issues
- If password prompts hang or fail, ensure sshfs is launched in an environment where interaction is possible or use ssh-agent / key files.
- For automated mounts (systemd, fstab), use key-based auth and ensure the key is accessible to the service’s user. Use /etc/fuse.conf and user_allow_other for system mounts.
- Systemd and fstab mount quirks
- In /etc/fstab, an sshfs entry should include noauto,x-systemd.automount or _netdev to avoid boot hangs. Example:
- user@host:/remote/path /mnt/remote fuse.sshfs defaults,_netdev,users,idmap=user,reconnect 0 0
- For systemd unit mounts, set After=network-online.target and use automount units for resiliency.
- SELinux and AppArmor
- If client or server uses SELinux/AppArmor, check audit logs for denials. For SELinux, run ausearch/audit2why to find causes.
- AppArmor profiles may block sshfs fuse operations; adjust profiles or disable for testing.
- Debugging with verbosity
- Run sshfs with -o sshfs_debug -o loglevel=DEBUG -o kernel_debug to get detailed logs. Tail journalctl and server logs simultaneously.
Common error patterns and targeted fixes
-
Permission denied on otherwise-readable files
- Fix: use idmap=user or set uid/gid on mount; check server ACLs and SELinux contexts.
-
“Transport endpoint is not connected” or mount becomes inaccessible
- Fix: unmount (fusermount -u /mount) and remount; use reconnect option; check network stability.
-
“Stale file handle”
- Fix: remount; reduce caching (set low attr/entry/cache timeouts); avoid server-side replacements that change inodes during operations.
-
Slow directory listings or file opens
- Fix: enable caching if many small reads (increase attr/entry timeouts), or use direct_io for large files. Consider indexing remote data or using rsync for bulk operations.
-
Mount hangs during boot
- Fix: add _netdev and noauto or use systemd automount; ensure network-online.target dependency.
Performance tuning recommendations
- For many small files: increase attribute and entry cache timeouts (-o attr_timeout=60 -o entry_timeout=60) to reduce round-trips.
- For large sequential transfers: enable big_writes and direct_io when supported; use compression (-C) if CPU allows.
- For unstable networks: use reconnect and ServerAlive* options; consider rsync for transfers requiring reliability.
- For multi-user access: use allow_other and configure /etc/fuse.conf appropriately.
Alternatives and when to stop troubleshooting
If SSHFS continues to cause issues despite fixes, consider alternatives:
- rsync or scp for one-time or bulk transfers.
- SFTP clients (lftp, sftp) for interactive use.
- NFS, Samba/CIFS for LAN environments where performance and POSIX semantics are critical.
- Rclone, WebDAV, or dedicated file-syncing tools for cloud or cross-platform scenarios.
Example common sshfs commands
Mount with common options:
sshfs -o idmap=user,allow_other,reconnect,ServerAliveInterval=15,ServerAliveCountMax=3 user@host:/remote/path /mnt/remote
Unmount:
fusermount -u /mnt/remote
Mount in fstab (example):
user@host:/remote/path /mnt/remote fuse.sshfs noauto,_netdev,users,idmap=user,reconnect 0 0
Final notes
Keep SSH and FUSE up to date, prefer key-based authentication for automated mounts, and choose caching options that fit your workload. For intermittent issues, increase logging and compare client/server logs side-by-side to identify the root cause.