golang/go · error

missing GOSUMDB

Error message

missing GOSUMDB

What it means

This error occurs when the GOSUMDB environment variable, after whitespace splitting and known-name lookup, yields zero fields. GOSUMDB should contain at minimum a checksum database name or verifier key. An empty string or a string containing only whitespace after the knownGOSUMDB alias resolution triggers this.

Source

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

	// for sum.golang.org. If there are more
	// of these we should add a map like knownGOSUMDB.
	gosumdb := cfg.GOSUMDB
	if gosumdb == "sum.golang.google.cn" {
		gosumdb = "sum.golang.org https://sum.golang.google.cn"
	}

	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

View on GitHub (pinned to b6b368adc5)

Solutions

  1. Unset the variable to use the default: 'go env -u GOSUMDB' (the default is sum.golang.org).
  2. Set GOSUMDB to a valid value: 'go env -w GOSUMDB=sum.golang.org'.
  3. Check the origin: 'go env GOSUMDB' and trace where the empty value comes from (shell profile, Dockerfile ENV, CI variable).
  4. If using a custom checksum database, provide at least the name: 'go env -w GOSUMDB=your-sumdb-name' or a full key.

Example fix

# before
$ export GOSUMDB=""
$ go get example.com/mymodule
# missing GOSUMDB

# after
$ go env -u GOSUMDB   # reset to default (sum.golang.org)
$ go get example.com/mymodule
Defensive patterns

Strategy: validation

Validate before calling

// Validate GOSUMDB is non-empty
func validateGOSUMDBNotEmpty() error {
    out, err := exec.Command("go", "env", "GOSUMDB").Output()
    if err != nil { return err }
    val := strings.TrimSpace(string(out))
    if val == "" {
        return fmt.Errorf("GOSUMDB is empty; run: go env -u GOSUMDB")
    }
    return nil
}

Try / catch

if strings.Contains(stderr, "missing GOSUMDB") {
    // GOSUMDB is unset or whitespace-only
    // Auto-fix: exec.Command("go", "env", "-u", "GOSUMDB")
}

Prevention

When it happens

Trigger: GOSUMDB is set to an empty string or whitespace-only value. The string is split with strings.Fields (which handles multiple spaces), and if no tokens remain, the error fires. This can happen if GOSUMDB is explicitly set to '' or a script sets it to a variable that expands to nothing.

Common situations: A script sets GOSUMDB="" (empty string) explicitly, or assigns it from an undefined variable. A Docker build sets ENV GOSUMDB= with no value. A CI pipeline conditionally sets GOSUMDB and the condition evaluates to empty.

Related errors

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