What causes "MapViewOfFile %s: %w" in golang/go?

Use a 64-bit Go build (`GOARCH=amd64`).

MapViewOfFile %s: %w

Error message

MapViewOfFile %s: %w

What it means

Windows mmap helper: `syscall.MapViewOfFile` failed mapping the file view into the process address space after a successful `CreateFileMapping`. The wrapped error is the syscall result; the usual cause is insufficient reservable address space, prominent on 32-bit Windows.

Source

Thrown at src/cmd/go/internal/mmap/mmap_windows.go:32

)

func mmapFile(f *os.File) (Data, error) {
	st, err := f.Stat()
	if err != nil {
		return Data{}, err
	}
	size := st.Size()
	if size == 0 {
		return Data{f, nil}, nil
	}
	h, err := syscall.CreateFileMapping(syscall.Handle(f.Fd()), nil, syscall.PAGE_READONLY, 0, 0, nil)
	if err != nil {
		return Data{}, fmt.Errorf("CreateFileMapping %s: %w", f.Name(), err)
	}

	addr, err := syscall.MapViewOfFile(h, syscall.FILE_MAP_READ, 0, 0, 0)
	if err != nil {
		return Data{}, fmt.Errorf("MapViewOfFile %s: %w", f.Name(), err)
	}
	var info windows.MemoryBasicInformation
	err = windows.VirtualQuery(addr, &info, unsafe.Sizeof(info))
	if err != nil {
		return Data{}, fmt.Errorf("VirtualQuery %s: %w", f.Name(), err)
	}
	data := unsafe.Slice((*byte)(unsafe.Pointer(addr)), int(info.RegionSize))
	if len(data) < int(size) {
		// In some cases, especially on 386, we may not receive a in incomplete mapping:
		// one that is shorter than the file itself. Return an error in those cases because
		// incomplete mappings are not useful.
		return Data{}, fmt.Errorf("mmapFile: received incomplete mapping of file")
	}
	return Data{f, data[:int(size)]}, nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

Use a 64-bit Go build (`GOARCH=amd64`).
Clear the cache (`go clean -modcache`) to avoid the large file.
Reduce concurrent allocations / dependency count on 32-bit.

Defensive patterns

Strategy: retry

Try / catch

// Retry address-space pressure on Windows; clear cache if it persists.
for i := 0; i < 2; i++ {
    if err := runGoCmd(); err == nil || !isMapFailure(err) { return err }
    if i == 1 { _ = exec.Command("go", "clean", "-modcache").Run() }
}

Prevention

Use a 64-bit Go build on Windows for large module trees.
Close other memory-heavy processes during big builds.
Shrink the cache periodically to reduce mapping size.

When it happens

Trigger: Mapping a large file when the process address space is exhausted or fragmented; 32-bit process near the 2 GiB user-space ceiling.

Common situations: 32-bit (`GOARCH=386`) Windows builds; very large module files; address-space fragmentation from prior allocations.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/3280310e88cc15a0. Report an issue: GitHub.