{"record":{"id":"edbb783e02095a3d","repo":"hashicorp/vagrant","slug":"there-was-an-error-when-attempting-to-rsync-a-sync","errorCode":null,"errorMessage":"There was an error when attempting to rsync a synced folder.\nPlease inspect the error message below for more info.\n\nHost path: %{hostpath}\nGuest path: %{guestpath}\nCommand: %{command}\nError: %{stderr}","messagePattern":"There was an error when attempting to rsync a synced folder\\.\nPlease inspect the error message below for more info\\.\n\nHost path: %(.+?)\nGuest path: %(.+?)\nCommand: %(.+?)\nError: %(.+?)","errorType":"exception","errorClass":"Vagrant::Errors::RSyncError","httpStatus":null,"severity":"error","filePath":"plugins/synced_folders/rsync/helper.rb","lineNumber":224,"sourceCode":"        end\n\n        # If we have tasks to do before rsyncing, do those.\n        if machine.guest.capability?(:rsync_pre)\n          machine.guest.capability(:rsync_pre, opts)\n        end\n\n        if opts.include?(:verbose)\n          command_opts[:notify] = [:stdout, :stderr]\n          r = Vagrant::Util::Subprocess.execute(*(command + [command_opts])) {\n            |io_name,data| data.each_line { |line|\n              machine.ui.info(\"rsync[#{io_name}] -> #{line}\") }\n          }\n        else\n          r = Vagrant::Util::Subprocess.execute(*(command + [command_opts]))\n        end\n\n        if r.exit_code != 0\n          raise Vagrant::Errors::RSyncError,\n            command: command.map(&:inspect).join(\" \"),\n            guestpath: guestpath,\n            hostpath: hostpath,\n            stderr: r.stderr\n        end\n\n        # If we have tasks to do after rsyncing, do those.\n        if machine.guest.capability?(:rsync_post)\n          begin\n            machine.guest.capability(:rsync_post, opts)\n          rescue Vagrant::Errors::VagrantError => err\n            raise Vagrant::Errors::RSyncPostCommandError,\n              guestpath: guestpath,\n              hostpath: hostpath,\n              message: err.to_s\n          end\n        end\n      ensure","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/plugins/synced_folders/rsync/helper.rb#L206-L242","documentation":"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.","triggerScenarios":"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.","commonSituations":"Windows hosts lacking cwRsync; stale/injected SSH keys after reprovision; SELinux denying reads on hostpath; guest images without rsync; deep Windows paths exceeding limits.","solutions":["Read the stderr field — it is rsync's own diagnostic (code 23 = partial transfer, 12 = protocol/remote failure)","Confirm rsync is installed on both host and guest (rsync --version)","Verify the hostpath exists and is readable by the user running Vagrant","Make vagrant ssh work passwordlessly first — rsync tunnels over that SSH config","Clean stale ControlMaster sockets (or fix the controlpath dir permissions)"],"exampleFix":"# before\nconfig.vm.synced_folder \"src\", \"/app\", type: \"rsync\"   # hostpath typo -> RSyncError\n\n# after\nconfig.vm.synced_folder \"src/\", \"/app\", type: \"rsync\",\n  rsync__exclude: [\".git/\"]","handlingStrategy":"retry","validationCode":"# preflight both ends before enabling rsync folders\nreturn unless Vagrant::Util::Which.which(\"rsync\")\nreturn unless machine.communicate.test(\"command -v rsync\")","typeGuard":"def rsync_ready?(machine)\n  !Vagrant::Util::Which.which(\"rsync\").nil? && machine.state.id == :running\nend","tryCatchPattern":"retries = 2\nbegin\n  machine.env.action_runner.run(rsync_action, env)\nrescue Vagrant::Errors::RSyncError => e\n  retries -= 1\n  raise if retries.zero? || !e.extra_data[:stderr].include?(\"Connection reset\")\n  sleep 3\n  retry\nend","preventionTips":["Install rsync on host and guest (and in box images)","Keep vagrant ssh passwordless; rsync rides the same SSH config","Quote/avoid spaces in synced folder paths","Read the embedded stderr first - rsync codes (23, 12, 3) identify the class of failure"],"tags":["rsync","synced-folders","subprocess","ssh"],"backgroundTag":"rsync-failed","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}