golang/go · error

disallowed module version

Error message

disallowed module version

What it means

ErrDisallowed is the sentinel returned by version predicates passed to Query-like functions to reject a specific version. It also surfaces through CheckAllowed -> CheckExclusions (exclude directives) and CheckRetractions (retract directives), wrapped with module.VersionError context.

Source

Thrown at src/cmd/go/internal/modload/modfile.go:153

	return pruned
}

// CheckAllowed returns an error equivalent to ErrDisallowed if m is excluded by
// the main module's go.mod or retracted by its author. Most version queries use
// this to filter out versions that should not be used.
func (ld *Loader) CheckAllowed(ctx context.Context, m module.Version) error {
	if err := ld.CheckExclusions(ctx, m); err != nil {
		return err
	}
	if err := ld.CheckRetractions(ctx, m); err != nil {
		return err
	}
	return nil
}

// ErrDisallowed is returned by version predicates passed to Query and similar
// functions to indicate that a version should not be considered.
var ErrDisallowed = errors.New("disallowed module version")

// CheckExclusions returns an error equivalent to ErrDisallowed if module m is
// excluded by the main module's go.mod file.
func (ld *Loader) CheckExclusions(ctx context.Context, m module.Version) error {
	for _, mainModule := range ld.MainModules.Versions() {
		if index := ld.MainModules.Index(mainModule); index != nil && index.exclude[m] {
			return module.VersionError(m, errExcluded)
		}
	}
	return nil
}

var errExcluded = &excludedError{}

type excludedError struct{}

func (e *excludedError) Error() string     { return "excluded by go.mod" }
func (e *excludedError) Is(err error) bool { return err == ErrDisallowed }

View on GitHub (pinned to b6b368adc5)

Solutions

1. Pick a version that is neither excluded nor retracted (`go list -m -versions` to see them).
2. If you control the module, remove/adjust the exclude or retract directive.
3. Adjust the predicate to permit the version, if appropriate.

Example fix

// before
// go.mod: exclude example.com/lib v1.5.0
$ go get example.com/lib@v1.5.0   // disallowed module version

// after
$ go get example.com/lib@v1.5.1

// Before selecting a version, screen out excluded/retracted ones.
func nonDisallowedVersions(modPath string) ([]string, error) {
    out, err := exec.Command("go", "list", "-m", "-versions", modPath).Output()
    if err != nil { return nil, err }
    return strings.Fields(string(out))[1:], nil // skip module name token
}

import "errors"

func isDisallowed(err error) bool { return errors.Is(err, ErrDisallowed) }

if err := ld.CheckAllowed(ctx, m); err != nil {
    if isDisallowed(err) { /* choose another version */ }
}

When it happens

Trigger: A Query version predicate returns ErrDisallowed; or the queried version matches an `exclude` directive or a `retract` directive range in the main module's go.mod.

Common situations: Trying to upgrade to an excluded or retracted release; author retracting a bad release; custom predicates filtering versions.

Related errors

• ${GoModToolVersion} is required for tool directives in go.mo
• missing %s/go.mod at revision %s
• version %s is not canonical
• can only use path@version syntax with 'go get' and 'go insta
• syntax error

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