How To Fix Package Version Issues When You Swap the Golang Version in Your Go Mod File

This tutorial will teach you how to handle error messages like this:

module ariga.io/atlas@v0.31.1-0.20250212144724-069be8033e83 requires go >= 1.22.12 (running go 1.23.7)

They are caused by alterations to your Go version in the go.mod file. In my case, a change from 1.24 to 1.23.7.

Although Golang’s compatibility across versions is incredible, I still prefer to match Golang versions between my source code and test code. If you need a specific Golang version, and you’re getting the error above, this tutorial is for you.

Step 1 — Make Sure You Have the Right Go Version

Before running any commands, you need to check you have the right Golang version. You can do this with:

go version

If you see a version different from your desired version, you’ll need to install the version you want. You can learn how to do that here:

Managing Go installations - The Go Programming Language

If you want to have multiple versions, I suggest using a tool like:

• asdf
• mise-en-place

These will help you manage different versions easily.

Why Do You Need the Correct Version?

If you don’t have the correct version of Golang installed and in use on the command line, whatever version of Go you’re using will update your go.mod file to match its own version.

Step 2 — Delete Your Go Sum

The first step is simple: delete your go.sum file.

cd path/to/your/golang/directory

The go.sum file is a checksum database. It contains a SHA256 hash of the source code provided by each of your dependencies. This allows Golang to lock down the packages and versions used in your program.

Because different Golang versions require different package versions, you need to delete it so that it can be built again.

Step 3 — Clear Your Require Statements

Next, you need to clear the require statements you have in your go.mod file. Currently, you probably have something that looks like this:

require (
 github.com/lib/pq v1.10.9
 github.com/mattn/go-sqlite3 v1.14.32
 github.com/rs/zerolog v1.34.0
 github.com/smartystreets/goconvey v1.8.1
 github.com/testcontainers/testcontainers-go v0.39.0
)

require (
 ariga.io/atlas v0.31.1-0.20250212144724-069be8033e83 // indirect
 dario.cat/mergo v1.0.2 // indirect
 entgo.io/ent v0.14.4 // indirect
 github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
 github.com/Microsoft/go-winio v0.6.2 // indirect
 github.com/agext/levenshtein v1.2.3 // indirect
 github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect

Remove all of these statements.

Step 4 — Run Go Mod Tidy

Now you’re ready to rebuild your project with your version of Golang. Make sure at the top of your go.mod file you have:

go <your-version-here>

Then run:

GOTOOLCHAIN=local go mod tidy

In the terminal. The GOTOOLCHAIN=local command forces the go tool chain to use your locally defined Go version.

This should rebuild everything with your Golang version, and you’re good to go!

Troubleshooting — My Version Was Bumped

If you have a package incompatible with your chosen Golang version the go toolchain will automatically try to bump your version or fail. It fails when you use the GOTOOLCHAIN=local flag!

When this happens, you need to control what package the go toolchain downloads by adding require statements.

For example, I like to use testcontainers for clean testing. But, in 2025, their latest package version is only compatible with go >= 1.24.0. So I need to change what version is installed with a require statement.

To find the latest compatible version, do the following:

1. Visit the Golang package’s page, for example: testcontainers.
2. Visit the versions tab for the package, for example: testcontainers-versions.
3. Choose the first ever version of the package that was released.
4. Lock it in with a require statement.

This will give you something like this:

require(
  github.com/testcontainers/testcontainers-go v0.0.2
)

Version 0.0.2 is the first ever version of testcontainers. Now you can re-run:

GOTOOLCHAIN=local go mod tidy

This will automatically update testcontainer to the latest version that’s compatible with your go version, in my case 1.23.7. The result will be a require statement like this:

require(
  github.com/testcontainers/testcontainers-go v0.37.0
)

With your go <your-version-here> preserved! You can repeat this as necessary for all of your annoying packages.

Final Words

That’s it! I hope you find this useful when you’re trying to maximise package compatibility during testing. If you need this for a reason other than testing, let me know what it is in the comments. Happy Go modding!