hashicorp/vagrant · error · Vagrant::Errors::RSyncError

There was an error when attempting to rsync a synced folder.

Error message

There was an error when attempting to rsync a synced folder.
Please inspect the error message below for more info.

Host path: %{hostpath}
Guest path: %{guestpath}
Command: %{command}
Error: %{stderr}

What it means

The rsync helper assembles an rsync-over-SSH command (with guestpath, hostpath, and rsync args) and runs it via Vagrant::Util::Subprocess. A non-zero exit raises Vagrant::Errors::RSyncError interpolating the inspected command, host path, guest path, and captured stderr — everything rsync itself reported.

Source

Thrown at plugins/synced_folders/rsync/helper.rb:224

        end

        # If we have tasks to do before rsyncing, do those.
        if machine.guest.capability?(:rsync_pre)
          machine.guest.capability(:rsync_pre, opts)
        end

        if opts.include?(:verbose)
          command_opts[:notify] = [:stdout, :stderr]
          r = Vagrant::Util::Subprocess.execute(*(command + [command_opts])) {
            |io_name,data| data.each_line { |line|
              machine.ui.info("rsync[#{io_name}] -> #{line}") }
          }
        else
          r = Vagrant::Util::Subprocess.execute(*(command + [command_opts]))
        end

        if r.exit_code != 0
          raise Vagrant::Errors::RSyncError,
            command: command.map(&:inspect).join(" "),
            guestpath: guestpath,
            hostpath: hostpath,
            stderr: r.stderr
        end

        # If we have tasks to do after rsyncing, do those.
        if machine.guest.capability?(:rsync_post)
          begin
            machine.guest.capability(:rsync_post, opts)
          rescue Vagrant::Errors::VagrantError => err
            raise Vagrant::Errors::RSyncPostCommandError,
              guestpath: guestpath,
              hostpath: hostpath,
              message: err.to_s
          end
        end
      ensure

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Read the stderr field — it is rsync's own diagnostic (code 23 = partial transfer, 12 = protocol/remote failure)
2. Confirm rsync is installed on both host and guest (rsync --version)
3. Verify the hostpath exists and is readable by the user running Vagrant
4. Make vagrant ssh work passwordlessly first — rsync tunnels over that SSH config
5. Clean stale ControlMaster sockets (or fix the controlpath dir permissions)

Example fix

# before
config.vm.synced_folder "src", "/app", type: "rsync"   # hostpath typo -> RSyncError

# after
config.vm.synced_folder "src/", "/app", type: "rsync",
  rsync__exclude: [".git/"]

# preflight both ends before enabling rsync folders
return unless Vagrant::Util::Which.which("rsync")
return unless machine.communicate.test("command -v rsync")

def rsync_ready?(machine)
  !Vagrant::Util::Which.which("rsync").nil? && machine.state.id == :running
end

retries = 2
begin
  machine.env.action_runner.run(rsync_action, env)
rescue Vagrant::Errors::RSyncError => e
  retries -= 1
  raise if retries.zero? || !e.extra_data[:stderr].include?("Connection reset")
  sleep 3
  retry
end

When it happens

Trigger: rsync failing host-side: guest unreachable over SSH (auth/key problems), hostpath missing or unreadable, rsync missing on host or guest (surfacing as an rsync error over ssh), unwritable ControlMaster socket dir, spaces/special characters in paths, firewall blocking the tunneled connection.

Common situations: Windows hosts lacking cwRsync; stale/injected SSH keys after reprovision; SELinux denying reads on hostpath; guest images without rsync; deep Windows paths exceeding limits.

Related errors

• The box you're attempting to add has no available version th
• The box you're attempting to add doesn't support the provide
• The box you're attempting to add doesn't support the request
• The box you're attempting to add doesn't support the request
• The synced folder type '%{type}' is reporting as unusable fo

AI-assisted analysis of hashicorp/vagrant@35f3160f4a (2026-08-21). Data as JSON: /api/errors/edbb783e02095a3d. Report an issue: GitHub.