Diagnosing Vagrant Synced Folder Mount Failures Across Providers

Recognizable Condition

When a Vagrant VM starts but synced folders dont appear inside the guest or file writes are silently rejected the symptom is usually provider-specific. You might see Failed to mount synced folder Permission denied or simply an empty directory under /vagrant or the configured mount point. This guide covers the four primary providers VirtualBox shared folders NFS SMB and rsync and provides a repeatable diagnostic path.

Diagnostic Table

Ordered Diagnostic Checks

1. Confirm VM state run vagrant status. A running state is required for mount operations.
2. List active mounts run vagrant ssh -c 'mount | grep vagrant'. Note the filesystem type vboxsf nfs cifs rsync.
3. VirtualBox verification run VBoxControl --version on the host and compare with the guests lsmod | grep vboxsf output. If modules are absent or versions differ reinstall with vagrant vbguest --install ensure host and guest kernel headers compatible first.
4. Permission checks run id on the host and inside the guest. The default guest vagrant user has UID 1000. If your host user has a different UID adjust mount options via mount_options in the Vagrantfile e.g. mount_options uid 1000 gid 1000.
5. NFS server check from the host run showmount -e localhost. A successful export list confirms server-side configuration. If empty or error fix /etc/exports and restart nfsd. Then check host firewall rules for ports 111 2049 and 20048 distribution-specific firewall-cmd ufw or Windows Defender.
6. SMB credential check If smb_username or smb_password are omitted Vagrant may attempt guest-side caching which can stale. Add explicit credentials to the Vagrantfile config.vm.synced_folder '.', '/vagrant', type: 'smb', smb_username 'host_user', smb_password 'host_password'. Also verify SMB protocol compatibility; if the guest only supports SMBv1 and the host disables it enable SMBv2/v3 or adjust guest settings.
7. Rsync auto-sync By default rsync synced folders only transfer changes on vagrant up reload or provision. Activate auto-sync with vagrant rsync-auto or set rsync__auto true in the Vagrantfile to poll for changes every few seconds.
8. Firewall and service verification After provider-specific checks confirm that host-level firewalls allow required ports. Temporarily disabling the firewall can confirm whether it is the blocking factor.

Provider-Specific Fixes

VirtualBox

If lsmod grep vboxsf returns nothing the Guest Additions installation is missing or mismatched. Ensure the box image includes compatible kernel headers then run vagrant vbguest --install. After installation reboot the VM and re-verify lsmod grep vboxsf.

NFS

When showmount -e localhost succeeds but mounts still fail double-check /etc/exports permissions and the no_root_squash all_squash options if root access is required. Apply exports with exportfs -a and restart the NFS daemon. If a firewall was the root cause add the necessary rules for your distribution before retrying.

SMB

Add smb_username and smb_password to the Vagrantfile if credentials are not cached. If SMBv1 is disabled either enable SMBv2/v3 on the host or adjust the guest OS to prefer newer protocols. On Windows hosts verify SMB protocol status before changing settings.

rsync

To push live edits run vagrant rsync-auto inside the VM directory or add config.vm.synced_folder '.', '/vagrant', type: 'rsync', rsync__auto true to the Vagrantfile. Remember that the first sync occurs on vagrant up; subsequent auto-syncs depend on the rsync-auto process staying alive.

Escalation Criteria

• If Guest Additions reinstallation fails due to missing kernel headers align host and guest kernel versions or rebuild the box image from a compatible base.
• If NFS exports are correct and firewalls are open but mounts still error investigate server-side rpcbind logs journalctl -u nfs-server on Linux or consider an alternative provider.
• If SMB credentials repeatedly prompt despite explicit configuration verify that the host username exists on the guest system and that no conflicting credentials are stored in the guests credential manager.
• If rsync auto-sync consumes excessive CPU consider increasing the poll interval or switching to manual vagrant rsync runs after vagrant up.

Practical verification after each fix re-run vagrant ssh -c 'mount | grep vagrant' and attempt touch /vagrant/test-file. Successful mount and writable permissions confirm the resolution.