lima-vm/lima · error

failed to construct wsl boot.sh script: %w

Error message

failed to construct wsl boot.sh script: %w

What it means

provisionVM renders the lima boot.sh script from a Go template (with CIDataPath substituted) using textutil.ExecuteTemplate. If template execution fails, this error wraps the underlying cause. It indicates the boot script could not be generated before it is written to a temp file and run inside WSL.

Source

Thrown at pkg/driver/wsl2/vm_windows.go:83

	if err != nil {
		return fmt.Errorf("failed to run `wsl.exe --terminate %s`: %w (out=%#q)",
			distroName, err, out)
	}
	return nil
}

//go:embed lima-init.TEMPLATE
var limaBoot string

// provisionVM starts Lima's boot process inside an already imported VM.
func provisionVM(ctx context.Context, instanceDir, instanceName, distroName string, errCh chan<- error) error {
	ciDataPath := filepath.Join(instanceDir, filenames.CIDataISODir)
	m := map[string]string{
		"CIDataPath": ciDataPath,
	}
	limaBootB, err := textutil.ExecuteTemplate(limaBoot, m)
	if err != nil {
		return fmt.Errorf("failed to construct wsl boot.sh script: %w", err)
	}
	limaBootFile, err := os.CreateTemp("", "lima-wsl2-boot-*.sh")
	if err != nil {
		return err
	}
	if _, err = limaBootFile.Write(limaBootB); err != nil {
		limaBootFile.Close()
		return err
	}
	limaBootFileWinPath := limaBootFile.Name()
	if err = limaBootFile.Close(); err != nil {
		return err
	}
	// path should be quoted and use \\ as separator
	bootFileWSLPath := strconv.Quote(limaBootFileWinPath)
	limaBootFilePathOnLinuxB, err := exec.CommandContext(
		ctx,
		"wsl.exe",

View on GitHub (pinned to dd909d0973)

Solutions

1. Reinstall/repair Lima — the embedded template asset may be corrupted in the build
2. Rebuild Lima from source cleanly (`make`) if using a self-compiled binary
3. Check the wrapped err for the exact template parse/execute failure and fix the template if it's a custom build
4. Update to a matching version of limactl and guest components (mixed-version installs can change template contracts)

Example fix

null

if err := driver.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to construct wsl boot.sh") {
        return fmt.Errorf("lima installation damaged (template render failed): %w; reinstall lima", err)
    }
    return err
}

When it happens

Trigger: Start() -> provisionVM when ExecuteTemplate returns an error — malformed/empty template asset, missing embedded limaBoot template, or writer failure during execution.

Common situations: Corrupted or modified Lima installation (embedded template assets missing/empty); template syntax broken in a custom build; template referencing unknown map keys if the map contract changed between Lima versions.

Related errors

• failed to run wslpath command: %w
• cannot use `--sync` with a wsl2 instance, the host directory
• failed to create Windows ISO entries: %w
• unimplemented
• failed to run `wsl.exe --distribution %s`: %w (out=%#q)

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