lima-vm/lima · error

failed to rsync to the guest %w

Error message

failed to rsync to the guest %w

What it means

limactl shell wraps the host-side rsync of the current working directory into the guest's synced workdir. This error is produced when the `rsyncDirectory` invocation (via the configured copy tool over SSH to `inst.Name`) exits non-zero. It means the initial host->guest directory sync failed, so the shell session is aborted before starting so the user doesn't work against stale or empty files in the guest.

Source

Thrown at cmd/limactl/shell.go:460

		paths := []string{
			hostCurrentDir,
			fmt.Sprintf("%s:%s", inst.Name, destRsyncDir),
		}
		rsync, err = copytool.New(ctx, string(copytool.BackendRsync), paths, &copytool.Options{
			Recursive: true,
			Verbose:   false,
			AdditionalArgs: []string{
				"--delete",
			},
		})
		if err != nil {
			return err
		}
		logrus.Debugf("using copy tool %#q", rsync.Name())

		if err := rsyncDirectory(ctx, cmd, rsync, paths); err != nil {
			return fmt.Errorf("failed to rsync to the guest %w", err)
		}
		logrus.Infof("Successfully synced host current directory to guest(%s) instance.", destRsyncDir)
	}

	if isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd()) {
		// required for showing the shell prompt: https://stackoverflow.com/a/626574
		sshArgs = append(sshArgs, "-t")
	}
	if _, present := os.LookupEnv("COLORTERM"); present {
		// SendEnv config is cumulative, with already existing options in ssh_config
		sshArgs = append(sshArgs, "-o", "SendEnv=COLORTERM")
	}
	logLevel := "ERROR"
	// For versions older than OpenSSH 8.9p, LogLevel=QUIET was needed to
	// avoid the "Shared connection to 127.0.0.1 closed." message with -t.
	olderSSH := sshutil.DetectOpenSSHVersion(ctx, sshExe).LessThan(*semver.New("8.9.0"))
	if olderSSH {
		logLevel = "QUIET"

View on GitHub (pinned to dd909d0973)

Solutions

1. Re-run the command; if the VM was still booting, wait until `limactl list` shows the instance RUNNING and sshd is up.
2. Verify rsync exists on the host and guest (`rsync --version`) and is >= 3.2.4, or avoid spaces/special chars in the host directory path.
3. Check the guest workdir permissions: `limactl shell <instance> ls -ld <destRsyncDir>` and fix ownership/permissions.
4. Inspect the wrapped error (rsync stderr is shown by rsyncDirectory) for the underlying cause (connection refused, auth failure, disk full).
5. If syncing is not needed, disable host workdir syncing for this invocation.

Example fix

// before
if err := rsyncDirectory(ctx, cmd, rsync, paths); err != nil {
    return fmt.Errorf("failed to rsync to the guest %w", err)
}
// after (retry once if the VM was still settling)
if err := rsyncDirectory(ctx, cmd, rsync, paths); err != nil {
    time.Sleep(2 * time.Second)
    if err := rsyncDirectory(ctx, cmd, rsync, paths); err != nil {
        return fmt.Errorf("failed to rsync to the guest: %w", err)
    }
}

limactl list | grep -q 'RUNNING' && command -v rsync >/dev/null && rsync --version | awk 'NR==1{print $3}' || echo 'instance not running or rsync missing'

// bash wrapper around limactl shell
for i in 1 2 3; do
  if limactl shell default; then break; fi
  sleep $((i * 2))
done

When it happens

Trigger: Running `limactl shell <instance>` (or `limactl start --sync-host-workdir` style flows) with syncHostWorkdir enabled, when the rsync child process from hostCurrentDir to `instance:destRsyncDir` fails: rsync binary missing or too old, SSH connection refused, permission denied on destRsyncDir, or path quoting issues (paths with spaces on rsync < 3.2.4).

Common situations: The guest VM was just started and sshd is not yet reachable; the rsync installed is older than 3.2.4 and the current directory path contains spaces or special characters; the host directory contains files the guest user cannot write (root-owned dirs); disk full in the guest; the instance was stopped between the mkdir and the rsync.

Related errors

• failed to sync back the changes from guest instance to host:
• failed to sync back the changes from guest instance to host
• failed to create the synced workdir in guest instance: %w
• rsync is required for `--sync` but not found: %w
• expected the depth of the host working directory (%#q) to be

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/8f7efd56b58d8ad2. Report an issue: GitHub.