golang/go · error

could not locate sumdb file: missing $GOPATH: %s

Error message

could not locate sumdb file: missing $GOPATH: %s

What it means

This error is thrown by dbClient.ReadConfig when it needs to read a sumdb state file from disk (the 'latest' tree head cached under GOPATH/pkg/sumdb/) but cfg.SumdbDir is empty. cfg.SumdbDir is derived from GOPATH; if GOPATH cannot be determined (cfg.GoPathError is set), SumdbDir stays empty and this error fires with the underlying GOPATH error.

Source

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

	})
	if errors.Is(err, fs.ErrNotExist) {
		// No proxies, or all proxies failed (with 404, 410, or were allowed
		// to fall back), or we reached an explicit "direct" or "off".
		c.base = c.direct
	} else if err != nil {
		c.baseErr = err
	}
}

// ReadConfig reads the key from c.key
// and otherwise reads the config (a latest tree head) from GOPATH/pkg/sumdb/<file>.
func (c *dbClient) ReadConfig(file string) (data []byte, err error) {
	if file == "key" {
		return []byte(c.key), nil
	}

	if cfg.SumdbDir == "" {
		return nil, fmt.Errorf("could not locate sumdb file: missing $GOPATH: %s",
			cfg.GoPathError)
	}
	targ := filepath.Join(cfg.SumdbDir, file)
	data, err = lockedfile.Read(targ)
	if errors.Is(err, fs.ErrNotExist) {
		// Treat non-existent as empty, to bootstrap the "latest" file
		// the first time we connect to a given database.
		return []byte{}, nil
	}
	return data, err
}

// WriteConfig rewrites the latest tree head.
func (*dbClient) WriteConfig(file string, old, new []byte) error {
	if file == "key" {
		// Should not happen.
		return fmt.Errorf("cannot write key")
	}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Set GOPATH explicitly: 'go env -w GOPATH=/path/to/gopath' or 'export GOPATH=/path/to/gopath'.
2. Ensure HOME is set: Go derives a default GOPATH from HOME/go if GOPATH is unset. Check with 'echo $HOME'.
3. Run 'go env GOPATH' to see the effective value and the error if it can't be determined.
4. In Docker containers, set HOME or GOPATH: 'ENV GOPATH=/go' or 'ENV HOME=/root'.

Example fix

# before: GOPATH unset in container
$ docker run --rm golang:alpine go mod download
# could not locate sumdb file: missing $GOPATH: ...

# after: set GOPATH
$ docker run --rm -e GOPATH=/go golang:alpine go mod download
# or use the default which requires HOME
$ docker run --rm -e HOME=/root golang:alpine go mod download

// Check GOPATH is set before running go mod commands
func validateGOPATH() error {
    out, err := exec.Command("go", "env", "GOPATH").Output()
    if err != nil { return err }
    val := strings.TrimSpace(string(out))
    if val == "" {
        return fmt.Errorf("GOPATH is empty; run: go env -w GOPATH=/path/to/go")
    }
    return nil
}

if strings.Contains(stderr, "could not locate sumdb file") && strings.Contains(stderr, "GOPATH") {
    // GOPATH not set; set it
    // exec.Command("go", "env", "-w", "GOPATH=/tmp/go")
}

When it happens

Trigger: The sumdb client needs to read its cached configuration (latest transparency-log tree head) from cfg.SumdbDir but GOPATH is unset or invalid. This happens during module operations that contact the checksum database (go mod download, go get, go mod verify) when GOPATH is not properly configured.

Common situations: GOPATH is not set and cannot be inferred (no default ~/go directory is usable). A CI environment or container that doesn't set GOPATH or HOME. A restricted filesystem where the GOPATH directory can't be created. GOENV or HOME environment variables point to unwritable locations.

Related errors

• missing GOSUMDB
• invalid GOSUMDB: too many fields
• not a directory
• GOPATH entry is relative; must be absolute path: %q
• %s exists but is not a directory

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