What causes "can't decode XML document using charset %q" in golang/go?

Check the repository's discovery page encoding: `curl -sL | head -5`

can't decode XML document using charset %q

Error message

can't decode XML document using charset %q

What it means

During VCS discovery (`go get`), the go tool fetches the vanity import path's HTML page and parses <meta> tags with an XML decoder. The CharsetReader callback only accepts UTF-8 and ASCII; any other declared charset is rejected so the user can see why the package wasn't downloaded.

Source

Thrown at src/cmd/go/internal/vcs/discovery.go:25

import (
	"encoding/xml"
	"fmt"
	"io"
	"strings"
)

// charsetReader returns a reader that converts from the given charset to UTF-8.
// Currently it only supports UTF-8 and ASCII. Otherwise, it returns a meaningful
// error which is printed by go get, so the user can find why the package
// wasn't downloaded if the encoding is not supported. Note that, in
// order to reduce potential errors, ASCII is treated as UTF-8 (i.e. characters
// greater than 0x7f are not rejected).
func charsetReader(charset string, input io.Reader) (io.Reader, error) {
	switch strings.ToLower(charset) {
	case "utf-8", "ascii":
		return input, nil
	default:
		return nil, fmt.Errorf("can't decode XML document using charset %q", charset)
	}
}

// parseMetaGoImports returns meta imports from the HTML in r.
// Parsing ends at the end of the <head> section or the beginning of the <body>.
func parseMetaGoImports(r io.Reader, mod ModuleMode) ([]metaImport, error) {
	d := xml.NewDecoder(r)
	d.CharsetReader = charsetReader
	d.Strict = false
	var imports []metaImport
	for {
		t, err := d.RawToken()
		if err != nil {
			if err != io.EOF && len(imports) == 0 {
				return nil, err
			}
			break
		}

View on GitHub (pinned to b6b368adc5)

Solutions

Check the repository's discovery page encoding: `curl -sL <vanity-url> | head -5`
If you control the hosting page, ensure it declares charset=UTF-8 or ASCII
Use the full VCS URL directly with `go get` via a replace directive or GOFLAGS workaround
Report the encoding issue to the vanity path maintainer

Example fix

<!-- before: page declares non-UTF-8 charset -->
<meta charset="ISO-8859-1">
<meta name="go-import" content="example.com/mymod git https://github.com/me/mymod">

<!-- after: use UTF-8 -->
<meta charset="UTF-8">
<meta name="go-import" content="example.com/mymod git https://github.com/me/mymod">

Defensive patterns

Strategy: try-catch

Validate before calling

# Pre-check the discovery page encoding before go get
URL="https://$(echo $IMPORT_PATH | cut -d/ -f1)"
ENCODING=$(curl -sIL "$URL" | grep -i content-type | grep -oiP 'charset=\K[^;\s]+' || echo 'unknown')
if [ "$ENCODING" != 'utf-8' ] && [ "$ENCODING" != 'ascii' ] && [ "$ENCODING" != 'us-ascii' ] && [ "$ENCODING" != 'unknown' ]; then
  echo "WARNING: page uses unsupported charset $ENCODING"
fi

Try / catch

# Catch the charset error and provide guidance
ERR=$(go get $IMPORT_PATH 2>&1)
if echo "$ERR" | grep -q 'can\'t decode XML document using charset'; then
  CHARSET=$(echo "$ERR" | grep -oP 'charset \K[^"]+')
  echo "Discovery page uses unsupported charset: $CHARSET"
  echo "Contact the vanity path maintainer or use a direct VCS URL"
fi

Prevention

Ensure vanity import pages declare charset=UTF-8
Use direct VCS URLs via replace directives if discovery pages are broken
Test discovery pages with curl before scripting go get

When it happens

Trigger: `go get` of a vanity import path whose hosting HTML page declares a charset other than UTF-8/ASCII in its XML declaration or <meta charset=...> tag (e.g., ISO-8859-1, Windows-1252, Shift_JIS).

Common situations: Legacy hosting servers sending Latin-1 encoded pages; misconfigured Content-Type or XML declaration on a vanity import page; a repo host that serves an unusual encoding.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/d1763c27cabfbf7d. Report an issue: GitHub.