go2cs diagnostic codes

go2cs reports problems with a GO2CS code from three sides. The converter (go2cs) prints its codes on stderr while it converts Go to C#. The source generators and analyzer in go2cs-gen report theirs in the C# build of a converted project, beside the compiler’s own CS codes, and so do go2cs’s MSBuild targets. Every code any side can report is listed below.

The number says which side reported it:

The converter prints each of its codes on stderr in MSBuild’s canonical error format; the command-line options page shows the line format. A go2cs-gen or build code appears in the build output like any compiler diagnostic, and a warning can be suppressed the usual way (NoWarn).

Code Side Severity Meaning What to do
GO2CS0001 go2cs-gen Warning A package class stem contains the lifted-name marker ᴛ, so a forwarder class the generator mints for a struct (<pkg>ᴛ<Struct>ᴛpkg or <pkg>ᴛ<Struct>ᴛxpkg) may collide with another struct’s (CS0101). No Go package in the standard library has such a stem. Report it as a go2cs issue, with the package path the message names. A CS0101 on a generated …ᴛpkg or …ᴛxpkg class is this collision.
GO2CS0002 go2cs-gen Warning A go2cs-gen record (an assembly or type attribute the converter emits) could not be read, so it was skipped and nothing was generated for it. The omission can only fail later and loudly, at the use site, or nothing was owed. Re-convert the package. A record the converter emitted that the generator cannot read is a go2cs issue; a record edited by hand is fixed or removed.
GO2CS0003 go2cs-gen Error A go2cs-gen record cannot be generated: for example a Go comment no record can carry, a record whose key would match two methods of one type, or a module initializer that would need a generated no-inlining declaring part. The build stays red at the record, so it cannot go green with members missing at run time. Read the message, which names the record and the reason. In converter output this is a go2cs issue; in a hand-written file, change the record it names.
GO2CS0004 go2cs-gen Error A C# string literal in converted code binds a type Go’s string is not: an object or interface parameter, a type parameter inferred as System.String, or a System.String overload chosen over the Go one. The program would see a C# string where Go has a Go string. In converter output, report it as a go2cs issue. In hand-written code inside a converted package, pass a Go string ((@string)"text"). A golib parameter that is meant to take a C# string is marked [GoTakesCSharpString].
GO2CS0005 go2cs-gen Error A C# string literal in converted code reaches an any (object) slot of a call that go2cs-gen cannot intercept, so the callee would see System.String where Go has a Go string. The message names the reason: a delegate (a Go func value), a generic method or a method of a generic type, a method generated code cannot call, a by-reference return, or a literal holding a lone UTF-16 surrogate. In converter output, report it as a go2cs issue: the converter passes a bare literal to an any slot only where the call can be intercepted. In hand-written code inside a converted package, pass a Go string ((@string)"text"u8).
GO2CS0006 go2cs-gen Error A C# string literal in converted code binds a member that does not take it as any, while another member of the same method group does: an overload beside the converted callee (often one taking go.@string, which C# prefers to object) has captured a call that Go makes to one function. Remove or rename the overload the message names, or pass a Go string explicitly if that overload is the one meant. In converter output with no hand-written overload, report it as a go2cs issue.
GO2CS0007 go2cs-gen Error A call to golib’s stack-append overload, append(in stackAppend<T>, ...), does not pass the buffer as a plain local of the calling method or lambda that no lambda captures (it passes a field, a new value, a captured or foreach local, or a local of another frame). The overload sets the buffer’s used flag through that reference, so any other argument would let a second empty append in the same call take Go’s stack buffer again. Pass the xᴷ local the converter declares at the entry of the function that appends. The converter never emits another shape; hand-written code that calls the overload declares its own local the same way.
GO2CS0008 go2cs-gen Error A GoImplicitConv record’s operator would return a box from a value: <T, ж<T>>, <T, ж<U>>, or <ж<T>, T>(Inverted = true). Go never converts a value to a pointer implicitly, so the record means the converter placed a value where Go passes a pointer. No operator is generated: such an operator would box a copy of the value, so a write through the box would never reach the original. The build fails at the record, and the site that needed the conversion fails to compile. In converter output, report it as a go2cs issue, naming the record and the failing site: the converter must pass the pointer’s box there. In hand-written code, pass the box (Ꮡx) instead of the value.
GO2CS0009 go2cs-gen Error A [GoLazy] holder class, which holds a Go package var built on its first read, does not hold exactly one static field named for the holder: lazyᴛX must hold the static field X, or for a var whose address is taken its box ᏑX (never marked Initial), and nothing else. The generator writes the var’s ref accessor (or the box’s) from that field, so it generates nothing for this holder, and a use of the var fails to compile while an unused var would be lost silently. In converter output, report it as a go2cs issue, naming the holder. In hand-written code, declare the holder as [GoLazy] partial class lazyᴛX { … static T X = …; } with no other member.
GO2CS0010 go2cs-gen Error A [GoBoundedGoroutine] record, which marks a go statement whose goroutine the converter proved cannot recurse so that it starts on the bounded stack reservation, does not land on a call of an unmarked goǃ rung: it names no file of the compilation, or one present twice, or its line and column hold no goǃ call, or the call binds another method or a GoStack-marked rung. A stale record could otherwise start an unproved goroutine on the small reservation, whose overflow ends the process. Re-convert the package, so that its package_info.cs records match its converted source. A record edited by hand is fixed or removed; a go statement without a record keeps the default reservation.
GO2CS0011 go2cs-gen Warning The assembly was converted with a converter refusal downgraded by -warn (today only GO2CS2002): its package_info.cs carries a [GoRefusalDowngraded(code, site, text)] record per refused site, and the site panics with the refusal text when it is reached. Reported in every build, so a project nobody converts again still shows it carries a known-broken path. Expected for a package converted with -warn. To clear it, reshape the code so the refusal no longer applies and convert without -warn.
GO2CS0012 go2cs-gen Error A type declares more methods than the .NET runtime loads on it: 65,521 for a static class, a struct or a class that derives from object, counting static and instance methods, constructors, accessors and operators, fewer for a class whose base types add virtual methods, and never more than 65,524 on any type, an interface included. The message gives the type’s count and its limit. The C# compiler has no such limit, so without this error the program would build and then throw TypeLoadException at the first use of the type. A package class holds every function and method of its Go package. The methods a struct promotes from an embedded field are not among them: each struct’s are in a class of its own (<pkg>ᴛ<Struct>ᴛpkg). A Go package with that many functions and methods of its own cannot be one package class: split the Go package. In converter output for a smaller package, report it as a go2cs issue, naming the type and the count in the message. In hand-written code, split the type.
GO2CS1000 converter Error The package did not load cleanly: an error go/packages does not classify. The package still converts best-effort. Fix the error the message names, so that go build succeeds for the package, then convert again.
GO2CS1001 converter Error The package did not load cleanly: a go list error, such as a missing module or no Go files for this build. Fix the module or build setup the message names (go.mod, GOOS/GOARCH, build tags) so that go list succeeds.
GO2CS1002 converter Error The package did not load cleanly: a Go parse error. The package still converts best-effort. Fix the Go syntax error at the position given.
GO2CS1003 converter Error The package did not fully type-check. It still converts best-effort, but code that depends on the failing expression is emitted untyped and will not compile. Fix the type error at the position given, so that go build succeeds for the package, then convert again.
GO2CS2001 converter Error Refused: a cgo source (import "C") is selected for this build without -cgo. Or, under -cgo, the package uses C in a way go2cs does not bind yet, and each such use is named on a line of its own with the phase that will cover it. The run exits non-zero and writes nothing. Convert with CGO_ENABLED=0, or exclude the file from the build. For a package whose C is calls of shared-library functions, convert it with -cgo (Limitations).
GO2CS2002 converter Error Refused: a generic instantiation over a pointer element (Walk[*Node] under N Tree[N]) needs a C# constraint proxy, and a method of the constraint passes a value that shares the element’s storage in Go (Tree.Children (returns []N); a map, channel or pointer of N, or a generic type carrying N). A proxy is a separate object per pointer and cannot forward that sharing. Each site and method is named, and the run exits non-zero. Instantiate over a value element (value-receiver methods), which needs no proxy. Or shape the method so it forwards exactly: return N itself, a tuple, a func or iterator (iter.Seq[N]), or an array [K]N. See generic constraints. Or, to convert the package anyway, pass -warn GO2CS2002: each site is then a warning, the method panics with this text when it is called, and the build reports GO2CS0011.
GO2CS2003 converter Error Refused: a conversion to a type the converter hand-converts (runtime’s guintptr family) takes the method’s own pointer receiver through unsafe.Pointer, for example guintptr(unsafe.Pointer(gp)) in a method of *g. The type stores the pointed-to value’s box, and a receiver is emitted as the value itself with no box to pass, so the conversion would hold a copy. The run exits non-zero. Hand-convert the method with a this ж<T> receiver (list it in manualConversionFuncs), as runtime’s g.guintptr is.
GO2CS2004 converter Error Retired: no longer reported. It refused a defined type written over an instantiated generic type, type Q pair[int] or type P[T any] pair[T], which go2cs now converts. The number stays reserved. Nothing: convert with a current go2cs.
GO2CS2005 converter Error Refused: a pointer type argument to a generic with a NON-self-referential method-set constraint (convertMapToOptions[O optionParser] called with &compilerOptionsParser{}) that the non-self constraint proxy cannot carry with Go’s semantics: a generic NAMED type; a constraint that mixes a type-term union with methods; a callee that also carries the type parameter in a slice, map, channel or pointer; a sibling type parameter whose constraint mentions it; inside the callee, its zero value used as a method receiver or converted to an interface; or the type parameter passed on to another generic under a different constraint. Each site is named with its reason, and the run exits non-zero. Until 1.26.11.1 these sites were reported as GO2CS2002. It cannot be downgraded with -warn: most of its sites would not compile, and a zero value boxed to an interface would run silently wrong. Instantiate over a value element, or reshape the generic so the type parameter appears only as a direct parameter or result. See generic constraints.
GO2CS2006 converter Error Refused: a generic call passes a []*T where the callee declares []N (N constrained by a method-set interface). go2cs passes that argument as an element-wise copy through the adapter, and the callee may write the slice (the first write is named), so its writes would land on the copy, not on the caller’s slice. Each site is named, and the run exits non-zero. It cannot be downgraded with -warn: the callee would write the copy and the program would run on with a silently wrong result. Make the callee leave the slice unwritten (no element assignment, append, sort, or hand-off to something that writes), declare the parameter []*T or over a value element type, or copy the slice explicitly where the write is not meant to be seen.
GO2CS2007 converter Warning One instantiation of a generic type satisfies a non-generic interface because a method the interface requires names the type’s own type parameter (box[point] as interface{ val() point }, where box[T] declares val() T). go2cs carries such a pair in a closed adapter class, and this use is one the carrier does not serve: the instantiation is a type argument constrained by the interface; or the type promotes a required method from an embedded field; or a second instantiation of the same type converts to the same interface in one package. The conversion goes on, and the C# build fails at the use the warning names. Convert the value through a named, non-generic type that declares the methods itself (type pointBox struct{ box[point] } with its own val), or pass the interface value in place of the type argument.
GO2CS2008 converter Error The converter failed on a file (a fault inside go2cs itself, recovered so the rest of the package converts), so that file’s output was not written: its .cs, or for a hand-owned file its .cs.auto review sibling. The file’s declarations are missing from the package, and so are its records in package_info.cs (interface implementations, position maps) and any import only it made. Each file is named as it is skipped, every other file is written, and the run ends with an error that names them all. It cannot be downgraded with -warn: a skipped file is not loud, since an init function, a method or an interface record can vanish with no compile error. Report it as a go2cs issue, naming the file and the fault in the message. -debug re-raises the fault with its stack, for the report.
GO2CS2009 converter Warning A struct type the inline-array rule selects (its own package converts it whole through unsafe.Pointer, or -inline-arrays forces its package) keeps golib’s array<T> storage, because a cap keeps it out (an array over 4096 bytes or 4096 elements, or a struct over 4096 bytes, at any level of its by-value closure) or its by-value closure holds a struct declared in another package, or (under the automatic rule) the package’s own non-test files use one of its array fields in a way an inline array cannot express: sliced, its address or an element’s address taken, or passed or stored as a whole value other than into an interface. Under the automatic rule a type is also kept out when it shares a reinterpret chain (*T)(unsafe.Pointer(e)) with a struct that keeps array<T> storage, or holds such a struct by value, so the two sides of every chain agree (golang.org/x/sys’s sockaddr decode is the case: RawSockaddrAny stays out with the family sockaddrs it is read as). The type converts exactly as it does without inline arrays. The warning names the type and the field, type or partner that keeps it out. Nothing, unless the struct is read from native memory: then the read is refused at run time by name. Splitting an over-cap array out of the struct, moving a foreign struct field into the package, or reaching the array only by index, len and range, admits it.
GO2CS2010 converter Error A reinterpret chain (*T)(unsafe.Pointer(e)), e a *X, whose two struct sides both hold arrays and disagree on inline storage: one side’s arrays are held inline, the other’s are not, so the two layouts differ. A side declared in another converted package is judged by that package’s package_info.cs record. The package is refused when -inline-arrays forces it, or when the admitted side is laid out by another package; under the automatic rule a pair inside one package agrees by keeping its admitted side out instead (GO2CS2009). It cannot be downgraded with -warn: a downgraded chain would read one side’s inline bytes as the other’s array<T> references, with no compile error. Make both sides agree: -inline-arrays=<package> forces the package’s whole declaration-local population on, or -inline-arrays=-<package> turns inline arrays off for it.
GO2CS2011 converter Error Refused: a function that a module implements in assembly, and that go2cs forwards to a managed body in golib (today golang.org/x/sys/cpu’s cpuid and xgetbv), is declared with another signature than that body implements. Forwarding it would call a body that answers another question, so the package is refused before any file is written, and the diagnostic names the function, the body, the signature the body implements and the declared one. It cannot be downgraded with -warn: it refuses the whole package, so there is no per-site code to produce. Convert against the module version whose signature the message names, or report the newer signature as a go2cs issue so its managed body can be updated.
GO2CS2012 converter Warning A function in a module outside the Go standard library has no Go body: it is implemented in assembly, or pulled with a //go:linkname that go2cs does not forward. It converts to a stub that throws NotImplementedException when called, and the conversion names each one. A program that never calls it is unaffected. If the program calls it, report it as a go2cs issue naming the function: a managed body (or a forward) is added for one that a converted program reaches.
GO2CS3001 build Error The C# compiler running the build is older than Roslyn 4.14, the version go2cs-gen is built against. The generator could not load, and Go string literals in any slots would reach their callees as System.String. Build with the .NET 10 SDK and its own compiler. Remove any Microsoft.Net.Compilers.Toolset package that pins an older compiler.
GO2CS3002 build Error A package the build resolves was built below the go.* break floor, the newest go.* release that changed members compiled code binds ($(GoBreakFloor), set by go.lib). A converted module counts as built on the release its go2cs/source-metadata.txt names, or below the floor when it names none or, for a nugetgo.* package, ships no such file; a go.* package counts as its own version. Such a package restores beside the newer go.* packages and then fails at run time with MissingMethodException or a similar error. One diagnostic names each package, and one more stops the build before it compiles anything. With GoAllowBelowBreakFloor=true each package’s diagnostic is a warning instead, and the build goes on. Reference a revision of the module built on the floor release or later (on nuget.org a deprecated revision names its replacement; a -recurse=nuget conversion re-resolves with -nuget-map-refresh), or go.* packages of that release for a go.* package (or the package that brings it in). To build anyway and accept the run-time risk, set <GoAllowBelowBreakFloor>true</GoAllowBelowBreakFloor>. A package whose ID merely starts with go., and is not one of go2cs’s, is checked as a go.* package by its own version; the same opt-out is the remedy for that false positive. See Consuming Go from C#.
GO2CS3003 build Error The build is for a platform the go.* packages do not ship, on another operating system than Windows or with another architecture than a shipped build of its own (linux-riscv64, for one). A go.* package that differs by platform resolves no runtimes/ folder for it through the RID graph, so the program would compile against, and run, the Windows code in lib/. The message names the platform and the first such package. Build for a shipped platform (win-x64, linux-x64, linux-arm64, osx-x64, osx-arm64). A build that only compiles and knowingly wants the Windows code passes -p:GoAllowReferenceFlavor=true; the program then runs the Windows code. See Known issues.
GO2CS3004 build Warning The build is for a Windows platform the go.* packages do not ship (win-arm64). It compiles against, and runs, their Windows code, which is that operating system’s, so the program runs; what Go decides by architecture when the package was converted follows amd64. Nothing is required. Pass -p:GoAllowReferenceFlavor=true to silence it. See Known issues.

Adding a code

Each side has one registry, and a code is declared there and nowhere else:

A new code takes the next free number in its side’s range, and a row in the table above in the same change. The repository test TestGo2csDiagnosticCodeRegistry (src/go2cs/internal/repoguard) fails, naming the code, when a code is used in the source or in a user-facing page but not registered, registered twice, registered outside its side’s range, missing its row here, or (on the build side) raised by no task, and when a row names a code that is not registered.