Fix macOS Finder problems with Samba file shares

Change log

  • : Removed veto directives to address Finder error -8062. Added Troubleshooting section with more info.
  • : Guide updated for 2026 with additional performance improvements.
  • : Initial publication.

tl;dr: The changes below fix bizarre problems that MacOS Finder has while working with large Samba file shares.

Using MacOS’s Finder to work with large file share directories on my FreeBSD Samba server was sometimes giving me very strange, erratic behavior. It felt like the server had amnesia or was having hallucinations.

Symptoms included:

  • Directory contents would take a very long time to load.
  • Directory contents would disappear after browsing between sibling folders.
  • Directories would show the contents of different sibling folders.

The problem was really annoying and took me quite a while to figure out.

At first, I thought it was an issue with Finder. However, third-party file browsers like Commander One and Marta showed the same symptoms.

Since I built the file server myself, I assumed it must be a problem I inadvertently caused. However, Windows, Linux, Android, nor other FreeBSD clients didn’t suffer from these issues. Also, protocols other than SMB were not affected (FTP and SSH were working just fine).

Some articles online suggested that Samba itself was to blame, or that MacOS’s implementation of the Samba client was buggy. I even considered switching away from Samba to some other protocol, but that wouldn’t be ideal.

After doing a lot of reading and testing, I learned that Finder aggressively caches directory listings, and that cache system can be unreliable with large fileshares over Samba. And I also learned that out-of-the-box Samba configurations need to be tweaked slightly to improve connections for MacOS clients.

The fixes below were scoured from many places on the web, including Reddit posts, blog posts, Github repos, and a deep dive of the Samba configuration documentation. It took me a few months to track down the various configuration combinations needed, but now everything’s been working properly.

Server changes

On the server, make the following changes to your distribution’s Samba config file. On FreeBSD, the file is /usr/local/etc/smb4.conf:

[global]

# Enforce a minimum of Samba v2 (Vista / Server 2008) for client connections
min protocol = SMB2
server min protocol = SMB2

# Performance improvements
use sendfile = yes
ea support = yes
directory name cache size = 2500

# Improve compatibility with Macs
vfs objects = catia fruit streams_xattr
fruit:aapl = yes
fruit:nfs_aces = no
fruit:zero_file_id = yes
fruit:metadata = stream
fruit:resource = stream
fruit:encoding = native
spotlight backend = tracker

readdir_attr:aapl_rsize = no
readdir_attr:aapl_finder_info = no
readdir_attr:aapl_max_access = no

fruit:model = MacSamba
fruit:posix_rename = yes
fruit:veto_appledouble = no
fruit:wipe_intentionally_left_blank_rfork = yes
fruit:delete_empty_adfiles = yes

# 2026: No longer recommended as this causes Finder error -8062.
# veto files = /.DS_Store/.Trashes/
# delete veto files = yes

# (OPTIONAL) If this server isn't sharing printers,
# disable printer support to speed things up.
load printers = no
printing = bsd
printcap name = /dev/null
# NOTE: 'spoolss' is not a typo.
disable spoolss = yes

Spotlight searching of Samba shares is disabled by default, but you can add this line to each of your Samba share definitions in smb.conf to be absolutely sure:

[yourshare]
spotlight = no

Client changes

On the MacOS client computers, create /etc/nsmb.conf:

[default]

# Disable SMB v1
protocol_vers_map=6

# Disable NetBIOS
port445=no_netbios

# Use NTFS streams if supported
streams=yes

# Disable directory caching
dir_cache_max_cnt=0
dir_cache_max=0
dir_cache_off=yes

# Disable packet signing
signing_required=no

# Disable multi-channel connections and prioritize the wired ethernet connection
mc_prefer_wired=yes
mc_on=no

# Disable SMB session signing
validate_neg_off=yes

Applying the changes

  • Restart the Samba service on the server (FreeBSD: service samba_server restart)
  • Restart each client computer

When you reconnect to the server shares on your machines, these issues shouldn’t occur anymore.

Update 2026-04-28: Note on prior veto files configuration directives

Initially, I had configured Samba to prevent macOS clients from writing .DS_Store and other cruft to server shares to keep things clean and tidy. However, as of March 2026, I started encountering errors preventing folder copy operations from succeeding. See the solution below under Troubleshooting.

As this is a battle that I appear to have lost, and I can’t prevent the files from being written without causing errors, I’m considering writing a small cron job to purge all cruft files from my server shares on a regular basis.

Troubleshooting

When copying files from a macOS computer to the server, Finder reports the error “The operation can’t be completed because an unexpected error occurred (error code -8062).”
Finder reports this error when it isn’t able to write the .DS_Store files to the remote location. Disable the veto files and delete veto files configuration lines, restart Samba, and try again.