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:

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:

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:

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.