golangci/golangci-lint · error

invalid relative path mode %s, only (%s) allowed

Error message

invalid relative path mode %s, only (%s) allowed

What it means

This error comes from Run.Validate() when run.relative-path-mode is set to a value not present in fsutils.AllRelativePathModes(). Valid modes correspond to the fsutils RelativePathMode constants (go.mod, git root, working directory, etc.). The check keeps invalid path-resolution modes from reaching the runner.

Source

Thrown at pkg/config/run.go:44

	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.relative-path-mode to a valid mode from fsutils.AllRelativePathModes() (e.g. gomod, git-root, wd)
2. Remove the key to use the default mode
3. Check the fsutils basepath.go switch cases for the exact accepted strings in your version

Example fix

// before
run:
  relative-path-mode: gitroot
// after
run:
  relative-path-mode: git-root

validModes := fsutils.AllRelativePathModes()
if cfg.Run.RelativePathMode != "" && !slices.Contains(validModes, cfg.Run.RelativePathMode) {
  return fmt.Errorf("relative-path-mode must be one of %v", validModes)
}

When it happens

Trigger: Setting run.relative-path-mode in .golangci.yml to an unsupported string (e.g. 'gomod-root', 'project') instead of one of the fsutils relative path modes, then running golangci-lint or Run.Validate().

Common situations: Typos like 'gitroot' instead of 'git-root'; copying values between golangci-lint major versions where mode names changed; guessing mode names without checking fsutils.

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

• unsupported output path mode %q
• the configuration contains invalid elements
• root field 'version' is required
• no plugins defined
• field 'module' is required

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