Text file
doc/godebug.md
Documentation: doc
1---
2title: "Go, Backwards Compatibility, and GODEBUG"
3layout: article
4---
5
6<!--
7This document is kept in the Go repo, not x/website,
8because it documents the full list of known GODEBUG settings,
9which are tied to a specific release.
10-->
11
12## Introduction {#intro}
13
14Go's emphasis on backwards compatibility is one of its key strengths.
15There are, however, times when we cannot maintain complete compatibility.
16If code depends on buggy (including insecure) behavior,
17then fixing the bug will break that code.
18New features can also have similar impacts:
19enabling the HTTP/2 use by the HTTP client broke programs
20connecting to servers with buggy HTTP/2 implementations.
21These kinds of changes are unavoidable and
22[permitted by the Go 1 compatibility rules](/doc/go1compat).
23Even so, Go provides a mechanism called GODEBUG to
24reduce the impact such changes have on Go developers
25using newer toolchains to compile old code.
26
27A GODEBUG setting is a `key=value` pair
28that controls the execution of certain parts of a Go program.
29The environment variable `GODEBUG`
30can hold a comma-separated list of these settings.
31For example, if a Go program is running in an environment that contains
32
33 GODEBUG=http2client=0,http2server=0
34
35then that Go program will disable the use of HTTP/2 by default in both
36the HTTP client and the HTTP server.
37It is also possible to set the default `GODEBUG` for a given program
38(discussed below).
39
40When preparing any change that is permitted by Go 1 compatibility
41but may nonetheless break some existing programs,
42we first engineer the change to keep as many existing programs working as possible.
43For the remaining programs,
44we define a new GODEBUG setting that
45allows individual programs to opt back in to the old behavior.
46A GODEBUG setting may not be added if doing so is infeasible,
47but that should be extremely rare.
48
49GODEBUG settings added for compatibility will be maintained
50for a minimum of two years (four Go releases).
51Some, such as `http2client` and `http2server`,
52will be maintained much longer, even indefinitely.
53
54When possible, each GODEBUG setting has an associated
55[runtime/metrics](/pkg/runtime/metrics/) counter
56named `/godebug/non-default-behavior/<name>:events`
57that counts the number of times a particular program's
58behavior has changed based on a non-default value
59for that setting.
60For example, when `GODEBUG=http2client=0` is set,
61`/godebug/non-default-behavior/http2client:events`
62counts the number of HTTP transports that the program
63has configured without HTTP/2 support.
64
65## Default GODEBUG Values {#default}
66
67When a GODEBUG setting is not listed in the environment variable,
68its value is derived from three sources:
69the defaults for the Go toolchain used to build the program,
70amended to match the Go version listed in `go.mod`,
71and then overridden by explicit `//go:debug` lines in the program.
72
73The [GODEBUG History](#history) gives the exact defaults for each Go toolchain version.
74For example, Go 1.21 introduces the `panicnil` setting,
75controlling whether `panic(nil)` is allowed;
76it defaults to `panicnil=0`, making `panic(nil)` a run-time error.
77Using `panicnil=1` restores the behavior of Go 1.20 and earlier.
78
79When compiling a work module or workspace that declares
80an older Go version, the Go toolchain amends its defaults
81to match that older Go version as closely as possible.
82For example, when a Go 1.21 toolchain compiles a program,
83if the work module's `go.mod` or the workspace's `go.work`
84says `go` `1.20`, then the program defaults to `panicnil=1`,
85matching Go 1.20 instead of Go 1.21.
86
87Because this method of setting GODEBUG defaults was introduced only in Go 1.21,
88programs listing versions of Go earlier than Go 1.20 are configured to match Go 1.20,
89not the older version.
90
91To override these defaults, a main package's source files
92can include one or more `//go:debug` directives at the top of the file
93(preceding the `package` statement).
94Continuing the `panicnil` example, if the module or workspace is updated
95to say `go` `1.21`, the program can opt back into the old `panic(nil)`
96behavior by including this directive:
97
98 //go:debug panicnil=1
99
100Starting in Go 1.21, the Go toolchain treats a `//go:debug` directive
101with an unrecognized GODEBUG setting as an invalid program.
102Programs with more than one `//go:debug` line for a given setting
103are also treated as invalid.
104(Older toolchains ignore `//go:debug` directives entirely.)
105
106The defaults that will be compiled into a main package
107are reported by the command:
108
109{{raw `
110 go list -f '{{.DefaultGODEBUG}}' my/main/package
111`}}
112
113Only differences from the base Go toolchain defaults are reported.
114
115When testing a package, `//go:debug` lines in the `*_test.go`
116files are treated as directives for the test's main package.
117In any other context, `//go:debug` lines are ignored by the toolchain;
118`go` `vet` reports such lines as misplaced.
119
120## GODEBUG History {#history}
121
122This section documents the GODEBUG settings introduced and removed in each major Go release
123for compatibility reasons.
124Packages or programs may define additional settings for internal debugging purposes;
125for example,
126see the [runtime documentation](/pkg/runtime#hdr-Environment_Variables)
127and the [go command documentation](/cmd/go#hdr-Build_and_test_caching).
128
129### Go 1.22
130
131Go 1.22 adds a configurable limit to control the maximum acceptable RSA key size
132that can be used in TLS handshakes, controlled by the [`tlsmaxrsasize` setting](/pkg/crypto/tls#Conn.Handshake).
133The default is tlsmaxrsasize=8192, limiting RSA to 8192-bit keys. To avoid
134denial of service attacks, this setting and default was backported to Go
1351.19.13, Go 1.20.8, and Go 1.21.1.
136
137Go 1.22 made it an error for a request or response read by a net/http
138client or server to have an empty Content-Length header.
139This behavior is controlled by the `httplaxcontentlength` setting.
140
141Go 1.22 changed the behavior of ServeMux to accept extended
142patterns and unescape both patterns and request paths by segment.
143This behavior can be controlled by the
144[`httpmuxgo121` setting](/pkg/net/http/#ServeMux).
145
146Go 1.22 added the [Alias type](/pkg/go/types#Alias) to [go/types](/pkg/go/types)
147for the explicit representation of [type aliases](/ref/spec#Type_declarations).
148Whether the type checker produces `Alias` types or not is controlled by the
149[`gotypesalias` setting](/pkg/go/types#Alias).
150For Go 1.22 it defaults to `gotypesalias=0`.
151For Go 1.23, `gotypealias=1` will become the default.
152This setting will be removed in a future release, Go 1.24 at the earliest.
153
154Go 1.22 changed the default minimum TLS version supported by both servers
155and clients to TLS 1.2. The default can be reverted to TLS 1.0 using the
156[`tls10server` setting](/pkg/crypto/tls/#Config).
157
158Go 1.22 changed the default TLS cipher suites used by clients and servers when
159not explicitly configured, removing the cipher suites which used RSA based key
160exchange. The default can be revert using the [`tlsrsakex` setting](/pkg/crypto/tls/#Config).
161
162Go 1.22 disabled
163[`ConnectionState.ExportKeyingMaterial`](/pkg/crypto/tls/#ConnectionState.ExportKeyingMaterial)
164when the connection supports neither TLS 1.3 nor Extended Master Secret
165(implemented in Go 1.21). It can be reenabled with the [`tlsunsafeekm`
166setting](/pkg/crypto/tls/#ConnectionState.ExportKeyingMaterial).
167
168Go 1.22 changed how the runtime interacts with transparent huge pages on Linux.
169In particular, a common default Linux kernel configuration can result in
170significant memory overheads, and Go 1.22 no longer works around this default.
171To work around this issue without adjusting kernel settings, transparent huge
172pages can be disabled for Go memory with the
173[`disablethp` setting](/pkg/runtime#hdr-Environment_Variable).
174This behavior was backported to Go 1.21.1, but the setting is only available
175starting with Go 1.21.6.
176This setting may be removed in a future release, and users impacted by this issue
177should adjust their Linux configuration according to the recommendations in the
178[GC guide](/doc/gc-guide#Linux_transparent_huge_pages), or switch to a Linux
179distribution that disables transparent huge pages altogether.
180
181Go 1.22 added contention on runtime-internal locks to the [`mutex`
182profile](/pkg/runtime/pprof#Profile). Contention on these locks is always
183reported at `runtime._LostContendedRuntimeLock`. Complete stack traces of
184runtime locks can be enabled with the [`runtimecontentionstacks`
185setting](/pkg/runtime#hdr-Environment_Variable). These stack traces have
186non-standard semantics, see setting documentation for details.
187
188Go 1.22 added a new [`crypto/x509.Certificate`](/pkg/crypto/x509/#Certificate)
189field, [`Policies`](/pkg/crypto/x509/#Certificate.Policies), which supports
190certificate policy OIDs with components larger than 31 bits. By default this
191field is only used during parsing, when it is populated with policy OIDs, but
192not used during marshaling. It can be used to marshal these larger OIDs, instead
193of the existing PolicyIdentifiers field, by using the
194[`x509usepolicies` setting.](/pkg/crypto/x509/#CreateCertificate).
195
196
197### Go 1.21
198
199Go 1.21 made it a run-time error to call `panic` with a nil interface value,
200controlled by the [`panicnil` setting](/pkg/builtin/#panic).
201
202Go 1.21 made it an error for html/template actions to appear inside of an ECMAScript 6
203template literal, controlled by the
204[`jstmpllitinterp` setting](/pkg/html/template#hdr-Security_Model).
205This behavior was backported to Go 1.19.8+ and Go 1.20.3+.
206
207Go 1.21 introduced a limit on the maximum number of MIME headers and multipart
208forms, controlled by the
209[`multipartmaxheaders` and `multipartmaxparts` settings](/pkg/mime/multipart#hdr-Limits)
210respectively.
211This behavior was backported to Go 1.19.8+ and Go 1.20.3+.
212
213Go 1.21 adds the support of Multipath TCP but it is only used if the application
214explicitly asked for it. This behavior can be controlled by the
215[`multipathtcp` setting](/pkg/net#Dialer.SetMultipathTCP).
216
217There is no plan to remove any of these settings.
218
219### Go 1.20
220
221Go 1.20 introduced support for rejecting insecure paths in tar and zip archives,
222controlled by the [`tarinsecurepath` setting](/pkg/archive/tar/#Reader.Next)
223and the [`zipinsecurepath` setting](/pkg/archive/zip/#NewReader).
224These default to `tarinsecurepath=1` and `zipinsecurepath=1`,
225preserving the behavior of earlier versions of Go.
226A future version of Go may change the defaults to
227`tarinsecurepath=0` and `zipinsecurepath=0`.
228
229Go 1.20 introduced automatic seeding of the
230[`math/rand`](/pkg/math/rand) global random number generator,
231controlled by the [`randautoseed` setting](/pkg/math/rand/#Seed).
232
233Go 1.20 introduced the concept of fallback roots for use during certificate verification,
234controlled by the [`x509usefallbackroots` setting](/pkg/crypto/x509/#SetFallbackRoots).
235
236Go 1.20 removed the preinstalled `.a` files for the standard library
237from the Go distribution.
238Installations now build and cache the standard library like
239packages in other modules.
240The [`installgoroot` setting](/cmd/go#hdr-Compile_and_install_packages_and_dependencies)
241restores the installation and use of preinstalled `.a` files.
242
243There is no plan to remove any of these settings.
244
245### Go 1.19
246
247Go 1.19 made it an error for path lookups to resolve to binaries in the current directory,
248controlled by the [`execerrdot` setting](/pkg/os/exec#hdr-Executables_in_the_current_directory).
249There is no plan to remove this setting.
250
251### Go 1.18
252
253Go 1.18 removed support for SHA1 in most X.509 certificates,
254controlled by the [`x509sha1` setting](/pkg/crypto/x509#InsecureAlgorithmError).
255This setting will be removed in a future release, Go 1.22 at the earliest.
256
257### Go 1.10
258
259Go 1.10 changed how build caching worked and added test caching, along
260with the [`gocacheverify`, `gocachehash`, and `gocachetest` settings](/cmd/go/#hdr-Build_and_test_caching).
261There is no plan to remove these settings.
262
263### Go 1.6
264
265Go 1.6 introduced transparent support for HTTP/2,
266controlled by the [`http2client`, `http2server`, and `http2debug` settings](/pkg/net/http/#hdr-HTTP_2).
267There is no plan to remove these settings.
268
269### Go 1.5
270
271Go 1.5 introduced a pure Go DNS resolver,
272controlled by the [`netdns` setting](/pkg/net/#hdr-Name_Resolution).
273There is no plan to remove this setting.
View as plain text