doc/godebug.md

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