{"record":{"id":"3e9828636a57ca81","repo":"golang/go","slug":"disallowed-module-version","errorCode":null,"errorMessage":"disallowed module version","messagePattern":"disallowed module version","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/modload/modfile.go","lineNumber":153,"sourceCode":"\treturn pruned\n}\n\n// CheckAllowed returns an error equivalent to ErrDisallowed if m is excluded by\n// the main module's go.mod or retracted by its author. Most version queries use\n// this to filter out versions that should not be used.\nfunc (ld *Loader) CheckAllowed(ctx context.Context, m module.Version) error {\n\tif err := ld.CheckExclusions(ctx, m); err != nil {\n\t\treturn err\n\t}\n\tif err := ld.CheckRetractions(ctx, m); err != nil {\n\t\treturn err\n\t}\n\treturn nil\n}\n\n// ErrDisallowed is returned by version predicates passed to Query and similar\n// functions to indicate that a version should not be considered.\nvar ErrDisallowed = errors.New(\"disallowed module version\")\n\n// CheckExclusions returns an error equivalent to ErrDisallowed if module m is\n// excluded by the main module's go.mod file.\nfunc (ld *Loader) CheckExclusions(ctx context.Context, m module.Version) error {\n\tfor _, mainModule := range ld.MainModules.Versions() {\n\t\tif index := ld.MainModules.Index(mainModule); index != nil && index.exclude[m] {\n\t\t\treturn module.VersionError(m, errExcluded)\n\t\t}\n\t}\n\treturn nil\n}\n\nvar errExcluded = &excludedError{}\n\ntype excludedError struct{}\n\nfunc (e *excludedError) Error() string     { return \"excluded by go.mod\" }\nfunc (e *excludedError) Is(err error) bool { return err == ErrDisallowed }","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/modload/modfile.go#L135-L171","documentation":"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.","triggerScenarios":"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.","commonSituations":"Trying to upgrade to an excluded or retracted release; author retracting a bad release; custom predicates filtering versions.","solutions":["Pick a version that is neither excluded nor retracted (`go list -m -versions` to see them).","If you control the module, remove/adjust the exclude or retract directive.","Adjust the predicate to permit the version, if appropriate."],"exampleFix":"// before\n// go.mod: exclude example.com/lib v1.5.0\n$ go get example.com/lib@v1.5.0   // disallowed module version\n\n// after\n$ go get example.com/lib@v1.5.1","handlingStrategy":"validation","validationCode":"// Before selecting a version, screen out excluded/retracted ones.\nfunc nonDisallowedVersions(modPath string) ([]string, error) {\n    out, err := exec.Command(\"go\", \"list\", \"-m\", \"-versions\", modPath).Output()\n    if err != nil { return nil, err }\n    return strings.Fields(string(out))[1:], nil // skip module name token\n}","typeGuard":"import \"errors\"\n\nfunc isDisallowed(err error) bool { return errors.Is(err, ErrDisallowed) }","tryCatchPattern":"if err := ld.CheckAllowed(ctx, m); err != nil {\n    if isDisallowed(err) { /* choose another version */ }\n}","preventionTips":["Review a module's `retract` directives before pinning a version.","Audit your own `exclude` directives when versions fail to resolve.","Prefer latest stable versions, which are rarely retracted."],"tags":["exclusions","retractions","versioning","go-mod"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}