golangci/golangci-lint · error

invalid modules download path %s, only (%s) allowed

Error message

invalid modules download path %s, only (%s) allowed

What it means

This error comes from Run.Validate() when run.modules-download-mode is set to a value other than one of the Go module download modes allowed by `go help modules`: 'mod', 'readonly', or 'vendor'. The value is passed through to the go toolchain, so anything invalid is rejected early. It is a configuration allowlist check, not a runtime failure.

Source

Thrown at pkg/config/run.go:38

	RelativePathMode string `mapstructure:"relative-path-mode"`

	BuildTags           []string `mapstructure:"build-tags"`
	ModulesDownloadMode string   `mapstructure:"modules-download-mode"`
	EnableBuildVCS      bool     `mapstructure:"enable-build-vcs"`

	ExitCodeIfIssuesFound int  `mapstructure:"issues-exit-code"`
	AnalyzeTests          bool `mapstructure:"tests"`

	AllowParallelRunners bool `mapstructure:"allow-parallel-runners"`
	AllowSerialRunners   bool `mapstructure:"allow-serial-runners"`
}

func (r *Run) Validate() error {
	// go help modules
	allowedModes := []string{"mod", "readonly", "vendor"}

	if r.ModulesDownloadMode != "" && !slices.Contains(allowedModes, r.ModulesDownloadMode) {
		return fmt.Errorf("invalid modules download path %s, only (%s) allowed", r.ModulesDownloadMode, strings.Join(allowedModes, "|"))
	}

	pathRelativeToModes := fsutils.AllRelativePathModes()

	if r.RelativePathMode != "" && !slices.Contains(pathRelativeToModes, r.RelativePathMode) {
		return fmt.Errorf("invalid relative path mode %s, only (%s) allowed", r.RelativePathMode, strings.Join(pathRelativeToModes, "|"))
	}

	return nil
}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Set run.modules-download-mode to exactly one of: mod, readonly, vendor
2. Or remove the run.modules-download-mode key to leave the go toolchain default (readonly)
3. Match the lowercase spelling exactly as shown by `go help modules`

Example fix

// before
run:
  modules-download-mode: ReadOnly
// after
run:
  modules-download-mode: readonly

allowed := []string{"", "mod", "readonly", "vendor"}
if !slices.Contains(allowed, cfg.Run.ModulesDownloadMode) {
  return fmt.Errorf("modules-download-mode must be one of mod|readonly|vendor")
}

When it happens

Trigger: Setting run.modules-download-mode in .golangci.yml to e.g. 'ReadOnly', 'mod-mode', or an empty-but-nonblank string, then running golangci-lint or Run.Validate().

Common situations: Capitalization mistakes ('Mod' vs 'mod'); using GOFLAGS-style values that aren't valid -mod flags; confusing this setting with unrelated download options.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• the configuration contains invalid elements
• root field 'version' is required
• no plugins defined
• field 'module' is required
• missing information: 'version' or 'path' should be provided

AI-assisted analysis of golangci/golangci-lint@ed7a235d2d (2026-09-02). Data as JSON: /api/errors/7c218476def6c071. Report an issue: GitHub.