What causes "invalid GOSUMDB: %v" in golang/go?

Use the default: 'go env -u GOSUMDB' (resets to sum.golang.org which is a known name).

invalid GOSUMDB: %v

Error message

invalid GOSUMDB: %v

What it means

This error occurs when the first field of GOSUMDB (the checksum database key) fails to parse as a valid note.Verifier key via note.NewVerifier. The Go checksum database uses signed transparency-log entries; the GOSUMDB key must be a valid note verifier key (format: 'name+hash+key'). If the key is malformed, note.NewVerifier returns an error which is wrapped here.

Source

Thrown at src/cmd/go/internal/modfetch/sumdb.go:121

	if gosumdb == "off" {
		return "", nil, fmt.Errorf("checksum database disabled by GOSUMDB=off")
	}

	key := strings.Fields(gosumdb)
	if len(key) >= 1 {
		if k := knownGOSUMDB[key[0]]; k != "" {
			key[0] = k
		}
	}
	if len(key) == 0 {
		return "", nil, fmt.Errorf("missing GOSUMDB")
	}
	if len(key) > 2 {
		return "", nil, fmt.Errorf("invalid GOSUMDB: too many fields")
	}
	vkey, err := note.NewVerifier(key[0])
	if err != nil {
		return "", nil, fmt.Errorf("invalid GOSUMDB: %v", err)
	}
	name := vkey.Name()

	// No funny business in the database name.
	direct, err := url.Parse("https://" + name)
	if err != nil || strings.HasSuffix(name, "/") || *direct != (url.URL{Scheme: "https", Host: direct.Host, Path: direct.Path, RawPath: direct.RawPath}) || direct.RawPath != "" || direct.Host == "" {
		return "", nil, fmt.Errorf("invalid sumdb name (must be host[/path]): %s %+v", name, *direct)
	}

	// Determine how to get to database.
	var base *url.URL
	if len(key) >= 2 {
		// Use explicit alternate URL listed in $GOSUMDB,
		// bypassing both the default URL derivation and any proxies.
		u, err := url.Parse(key[1])
		if err != nil {
			return "", nil, fmt.Errorf("invalid GOSUMDB URL: %v", err)
		}

View on GitHub (pinned to b6b368adc5)

Solutions

Use the default: 'go env -u GOSUMDB' (resets to sum.golang.org which is a known name).
For a custom sumdb, provide a valid verifier key in the correct format: a note verifier key looks like 'sum.golang.org/AOa...base64key'.
Double-check the key was copied in full without truncation or embedded whitespace.
If you don't need a custom sumdb, just set GOSUMDB=sum.golang.org or unset it entirely.

Example fix

# before: malformed key
$ go env -w GOSUMDB="mydb+invalid"
$ go mod download
# invalid GOSUMDB: invalid verifier key ...

# after: use default
$ go env -u GOSUMDB
$ go mod download

Defensive patterns

Strategy: validation

Validate before calling

// Validate GOSUMDB key is parseable (for custom sumdb)
import "golang.org/x/mod/sumdb/note"

func validateGOSUMDBKey(gosumdb string) error {
    fields := strings.Fields(gosumdb)
    if len(fields) == 0 { return fmt.Errorf("empty GOSUMDB") }
    // If it's a known name, it's valid
    known := map[string]bool{"sum.golang.org": true, "sum.golang.google.cn": true}
    if known[fields[0]] { return nil }
    // Otherwise try to parse as verifier key
    _, err := note.NewVerifier(fields[0])
    return err
}

Try / catch

if strings.Contains(stderr, "invalid GOSUMDB:") && !strings.Contains(stderr, "too many fields") {
    // Key format issue — reset to default
    // exec.Command("go", "env", "-u", "GOSUMDB")
}

Prevention

Use the default sum.golang.org unless a custom sumdb is truly needed
When providing a custom key, copy it exactly from the sumdb operator
Validate the key with note.NewVerifier before deploying
Avoid hand-typing base64-encoded keys

When it happens

Trigger: GOSUMDB's first field is neither a known name (sum.golang.org) nor a valid verifier key string. A custom GOSUMDB with a hand-typed or truncated key. A key with incorrect format (missing the +hash+ suffix, wrong encoding).

Common situations: A user sets GOSUMDB to a custom checksum database but provides a malformed verifier key. The key was copy-pasted incorrectly (truncated, extra whitespace inside). A custom sumdb deployment uses a non-standard key format. The knownGOSUMDB alias lookup failed because the name doesn't match any known entry.

Related errors

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