Resolving golangci-lint Go Version Conflicts in GitHub Actions

If you have encountered a build failure in your Go project’s GitHub Actions pipeline, you might see an error output similar to this:

 1run golangci-lint
 2
 3  Running [/home/runner/golangci-lint-1.64.8-linux-amd64/golangci-lint config path] in [/home/runner/work/go-pattern/go-pattern] ...
 4
 5  Running [/home/runner/golangci-lint-1.64.8-linux-amd64/golangci-lint run] in [/home/runner/work/go-pattern/go-pattern] ...
 6
 7  Error: can't load config: the Go language version (go1.24) used to build golangci-lint is lower than the targeted Go version (1.25.0)
 8
 9  Failed executing command with error: can't load config: the Go language version (go1.24) used to build golangci-lint is lower than the targeted Go version (1.25.0)
10
11  Error: golangci-lint exit with code 3
12
13  Ran golangci-lint in 90ms

This error usually appears when your repository’s Go version outpaces the Go version used to compile the golangci-lint binary that the action downloaded. Ensuring versions match is critical to ensure that the tools and applications are mutually compatible.

When this happens, here is the six-step process to get everything back in sync and passing:

1. Delete old configurations: Remove any existing golangci-lint.conf (or .golangci.yml) files to clear the slate.
2. Update the GitHub Action: Update the golangci-lint-action reference in your workflow to the latest version. Verify current versions against their official sources:
   • For golangci-lint-action, check the official repository (e.g. v9).
   • For Go itself, verify the latest stable release at go.dev.
3. Upgrade Go everywhere to match: Ensure your GitHub Actions workflows are using a go-version-file: go.mod strategy to keep the Go version automatically in sync with the codebase (unless you are explicitly testing a matrix of older versions).
4. Resolve issues iteratively: Rerun golangci-lint (ensure it is the same version) in a loop to resolve issues. Do not create a new config file immediately; instead, attempt to solve all issues by fixing a couple of them in each loop until they are all resolved. Note exceptions: If the project explicitly requires an older Go version for legacy compatibility, you should pin both the Go version and the golangci-lint binary version to compatible older releases instead of blindly upgrading to latest.
5. Format your code: Run go fmt ./....
6. Submit: Once everything is green and formatted, submit your changes.

Version Reference Table

Here is an example snippet showing an updated workflow configuration:

1      - uses: actions/checkout@v6
2      - uses: actions/setup-go@v6
3        with:
4          go-version-file: go.mod
5      - name: golangci-lint
6        uses: golangci/golangci-lint-action@v9
7        with:
8          version: latest

By following this process, you avoid getting stuck maintaining outdated lint configurations and keep your CI workflow aligned with the latest Go tools.