Known issues
This page lists specific bugs, each with a workaround. For the limits that come with running Go on .NET, and the rough spots real code hits today, see Limitations.
Writes through the address of another package’s pointer or interface variable are lost
Taking the address of a variable that another package exports gives a pointer to the variable itself when its
type is a value type. When its type is a pointer or an interface (&otherpkg.ErrMissing, for an
ErrMissing error), the pointer refers to a copy, and so does the address of runtime.MemProfileRate and of a
variable declared with a two-argument //go:linkname.
Limitations describes the cases and the
workarounds.
On Apple silicon, the standard library is the amd64 build
The packages ship for five platforms: win-x64, linux-x64, linux-arm64, osx-x64 and osx-arm64. The converted standard library
for macOS is built once, for darwin/amd64, and the same packages serve Intel and Apple-silicon Macs. On an
Apple-silicon Mac a converted program runs as a native arm64 .NET process:
runtime.GOARCHreadsarm64, as Go’s own program on the same Mac does. It is read from the process when the program starts, and theGOARCHsetting thatdebug.ReadBuildInforeturns andgo/build’s default context follow it;- everything Go decides by architecture at build time still follows
amd64. Go’s_arm64.gofiles are not in the packages,internal/goarchreportsamd64, and a constant Go computes from the architecture keeps itsamd64value.
So the converted runtime reads runtime.GOARCH as arm64 beside goarch.GOARCH as amd64 on the same Mac. That
asymmetry is deliberate: each runtime branch on GOARCH was checked and reads correctly on Apple silicon. The
processor features that the standard library reads at run time come from the real processor, so crypto/tls, for
one, prefers AES-GCM on Apple silicon as Go does there.
To avoid it, rely on runtime.GOARCH for the machine’s architecture, never on the presence of an
architecture-specific path in the standard library.
Platforms the packages do not ship
The go.* packages ship win-x64, linux-x64, linux-arm64, osx-x64 and osx-arm64. A package
whose code differs by platform carries one folder per platform under runtimes/, and a platform without one gets
the Windows build in lib/. A build resolves its platform the way .NET does at run time, so linux-musl-x64
(Alpine) uses the linux-x64 folder. For a platform that resolves to no folder, the build reports it:
GO2CS3003, an error, on another operating system, or on Linux with another architecture: linux-riscv64 would run the Windows build, and thelinux-x64build makes x64 system calls. The message names the platform and the first package without a folder for it.GO2CS3004, a warning, on a Windows platform the packages do not ship (win-arm64): the Windows build is that operating system’s, so the program runs. What Go decides by architecture when the package was converted followsamd64.
A cross-build for a shipped platform from an unshipped host is not affected: it names its platform with
-r <rid> (RuntimeIdentifier), and that platform has its folder.
To avoid it, build for one of the five shipped platforms. A build that only needs to compile, and knowingly wants
the Windows build (a test harness that never runs the program, say), passes -p:GoAllowReferenceFlavor=true. The
program then runs the Windows build wherever it runs. The property counts only on the command line: set in a
project file it changes nothing, so a library cannot switch the check off for the projects that build it.
A portable app built on a shipped platform and then RUN on another one is out of the build’s sight. At start-up
it prints a warning on standard error instead: for another operating system, and for the Linux build on another
architecture (linux-x64 run on linux-arm64).
On linux-arm64, a few standard-library members throw when called
The linux-arm64 build of the standard library has a few members that Go implements in arm64 assembly and that have
no managed body yet, so each throws when called: getisar0 and getpfr0 in internal/cpu; getisar0, getisar1,
getpfr0 and getzfr0 in vendor/golang.org/x/sys/cpu; load_g, save_g, spillArgs, unspillArgs,
asmcgocall_no_g, emptyfunc, panicBounds and panicExtend in runtime; and rawVforkSyscall in syscall.
Most of them exist only in the linux-arm64 build; the rest are routines that the other builds also leave without a
body.
To avoid it, do not call these members. All of them are internal to the standard library, so a program reaches one only through a standard-library path; if yours does, report the call path.
On macOS, a go statement past the system’s thread limit ends the program
By default each goroutine is an operating-system thread, and macOS caps how many threads one process may run. When a
program already has nearly that many goroutines alive, the next go statement throws
System.OutOfMemoryException, and the program ends unless something catches it. On the macOS 15 machines measured
the limit was about 2,000 goroutines on Apple silicon and about 3,000 on Intel; a Mac’s own limit is the
kern.num_taskthreads setting.
To avoid it, bound how many goroutines are alive at once, with a worker pool for example. Limitations has the details, under Goroutines are operating-system threads.
On Linux, a program with more than about 16,000 goroutines alive ends
By default each goroutine is an operating-system thread, and on Linux each .NET thread uses about four of the process’s memory
mappings. Linux caps the mappings at the vm.max_map_count setting, 65,530 by default. When a program has about
16,000 goroutines alive (measured on linux-x64, Ubuntu 22.04 under WSL, at the default setting), the next go statement fails with Fatal error. Failed to create RW mapping for RX memory,
and the program ends; nothing can catch it. A Go goroutine is not a thread, so the limit does not apply to Go itself.
To avoid it, bound how many goroutines are alive at once, with a worker pool for example. Two settings may raise
the limit, but neither has been measured: DOTNET_EnableWriteXorExecute=0 in the environment, which should cut the
mappings each thread uses, and a larger vm.max_map_count on the machine.
With go2cs 1.26.10.2 or earlier, a program converted with local standard-library references runs its standard library built Debug
Symptom. A program converted by go2cs 1.26.10.2 or earlier with plain -recurse or -recurse=module
references the standard library as local projects. Built with dotnet build -c Release in its folder, its
standard-library assemblies come out built Debug, unoptimized, and it runs slower than the same program built from
its .csproj (about 21 times slower on a TLS handshake under the JIT, on win-x64, on one development machine).
dotnet publish -c Release -r <rid> in the folder can fail with
ILLink : error IL1034: Root assembly 'golib' ... does not have entry point, and when it succeeds the published
program carries the same Debug assemblies. A -recurse=nuget conversion is not affected.
Cause. The converter wrote a .slnx beside each project, and in a folder that holds both, dotnet build and
dotnet publish take the solution. A solution build gives its configuration only to the projects the solution
lists, which were the program, golib and the analyzer, so every other standard-library project it built took its
default configuration, Debug. Publishing the solution also published golib as a project of its own.
Fix. Re-convert with go2cs 1.26.10.3 or later. It writes no solution for a local-reference conversion, and it removes the one an earlier converter wrote, if that file is unchanged.
Workaround. Build or publish the project, not a solution: run the command in a folder that holds no .sln
or .slnx, or name the .csproj (dotnet build <app>.csproj -c Release). Do not build these conversions through
a solution: the core projects a solution does not list build Debug. In Visual Studio, open the .csproj.
Ubuntu’s packaged .NET 10 can end a converted program early
On Ubuntu’s own build of .NET 10 (the dotnet installed with apt, runtime identifier ubuntu.*-x64), a
converted program that raises and recovers Go panics inside a hot loop can stop in one of two ways under the
default tiered compilation:
- a fatal
Internal CLR error. (0x80131506); - more often, a SILENT exit with code 0 and truncated output.
The fault needs the JIT’s on-stack replacement. Microsoft’s build of the same .NET version does not show it, and neither does Windows. No converted Go program is known to reproduce it; only a synthetic reproduction does.
To avoid it, run on Microsoft’s .NET build, or turn off quick JIT for loops, which removes on-stack replacement. A build property does it without touching the converted project:
dotnet build -p:TieredCompilationQuickJitForLoops=false
The built program’s runtimeconfig.json then carries
"System.Runtime.TieredCompilation.QuickJitForLoops": false. Or set it in the converted executable’s project
file, though the next conversion rewrites that file:
<TieredCompilationQuickJitForLoops>false</TieredCompilationQuickJitForLoops>
Converted executable projects carry this line, commented out. On linux-x64 (Canonical’s .NET 10, one 4-core
machine) it costs about 90 ms (16%) more startup time, and steady-state loop speed stays within measurement noise. It becomes the default if a converted Go program
ever reproduces the fault. Tuning converted code lists the runtime settings and
what each trades.
With the go.* 1.26.10.1 packages, a Native AOT program that uses the network can exit with an error
Symptom. A Native AOT executable (PublishAot) that references the go.* 1.26.10.1 packages exits with code 2
the first time it passes a pointer to certain Go structs to a system call. It prints
System.NotSupportedException: 'System.Runtime.CompilerServices.RuntimeHelpers.IsReferenceOrContainsReferences[System.UInt16]()' is missing native code
(the type in brackets varies). On Windows, a program that uses net or crypto/tls reaches it while setting up a
socket, in syscall.WSAIoctl. On Linux and macOS, the same system-call marshalling runs for a pointer to a struct that
holds a pointer, slice, string or array, and fails the same way. The same program run under the JIT (dotnet run, or
the converted project’s default ReadyToRun publish) is not affected. Measured on win-x64, linux-x64 and osx-arm64.
Cause. The runtime library’s system-call marshalling sorted a struct’s fields with a generic method it closed at run time, and a Native AOT image has no code for such a method.
Fix. Move to the go.* 1.26.10.2 packages or later.
Workaround on 1.26.10.1. Publish without Native AOT: the converted project’s default dotnet publish (ReadyToRun) and a
framework-dependent build run the same code under the JIT.
A Native AOT publish of a program that references the packages is slow and large
A program that references the go.* packages and publishes with Native AOT (PublishAot) runs. The check
that gates each release publishes a C# consumer of the packages and runs it on linux-x64, linux-arm64,
win-x64 and osx-arm64. On osx-x64 the publish is read when it finishes inside the hosted runner’s time limit, and reported as
not measured when it does not. A project that sets no trim mode of its own gets the packages’ default, partial,
which is the setting a converted project carries in its generated project file.
A full trim (TrimMode set to full) produces a program that runs as well. That is measured on win-x64, on
one development machine, with the 1.24.13.5 packages; the hosted check measures the default.
What it costs. With partial, Native AOT compiles every go.* assembly the program references in
full, not only the parts the program uses. For a small program that references about thirty of them, the
publish took under four minutes on a hosted CI runner for Linux and for Windows, about six minutes on a Mac
with Apple silicon and about eleven on an Intel Mac (measured 2026-10-14, with packages converted from Go
1.24.13). A converted project pays the same cost, because it uses the same setting. A build, dotnet run and a publish without
Native AOT are not affected. For the 1.24.13.7 packages and earlier, see the section that follows.
With the go.* 1.24.13.7 packages or earlier, a Native AOT publish can take hours or not finish
Symptom. A Native AOT publish (PublishAot) of a program that references the go.* 1.24.13.7 packages, or an
earlier release, does not finish or takes hours. The ILC compiler holds about 14 GB of memory and prints tens of
thousands of warnings that a method will always throw because a type from golib failed to load. Measured on
win-x64, on one development machine.
Cause. These releases were built before the fix to the runtime library’s generic cycle (see the Native AOT section). Native AOT expands that cycle until it reaches its nesting limit, and compiles each method that reaches past the limit to throw, which is what those warnings report.
Fix. Move to the go.* 1.26.10.1 packages or later. They carry the fix, and the 1.24.13.7 packages’ deprecation
notice already points to them.
Workaround on 1.24.13.7. Turn off identical-method folding in the project file:
<IlcFoldIdenticalMethodBodies>false</IlcFoldIdenticalMethodBodies>
The publish then finishes for most programs, at a cost: ILC peaked at about 28 GB, and the executable was 3.3 times
the size of the same program built against 1.26.10.1. A very large program can still fail at link (LNK1183,
“extended relocation count 9 less than 65535”) when the compiler’s object file passes 4 GiB, the COFF object
format’s limit, and the workaround has nothing more to offer it: move to 1.26.10.1. Measured on win-x64: every program
of the performance suite but the TLS handshake published this way; that one failed at link.
A single-file publish with composite ReadyToRun runs out of memory
A converted program’s project turns ReadyToRun on for dotnet publish. When the publish is also a single file
(-p:PublishSingleFile=true), the .NET SDK compiles ReadyToRun as a single composite image of the program and the
framework by default, and on that image the ReadyToRun compiler, crossgen2, expands golib’s nested generic types
until it runs out of memory: past 10 GB on a linux-x64 machine, failing with Insufficient memory and leaving
the build hanging. Compiled one assembly at a time, it does not. The publish profiles go2cs writes beside a
converted program (-p:PublishProfile=linux-x64 and the others) set
<PublishReadyToRunComposite>false</PublishReadyToRunComposite>, so a profile publish keeps ReadyToRun and is not
affected. A program converted by a go2cs earlier than 1.26.10.2 has profiles that turn ReadyToRun off instead,
since go2cs never overwrites a profile; replace their <PublishReadyToRun>false</PublishReadyToRun> with that
line to get ReadyToRun’s faster start back. A project converted by go2cs 1.26.10.3 or later carries the same line,
so a plain single-file publish is not affected either. A project converted by an earlier go2cs does not; on its command line,
turn the composite image off yourself:
dotnet publish -c Release -r linux-x64 -p:PublishSingleFile=true -p:PublishReadyToRunComposite=false
A publish that is not a single file never makes a composite image, so it is not affected.