Primcloud
Docs menu

Runtime versions

Which Go versions Primcloud installs, how to pin one via the go directive or the // +heroku goVersion build directive, and how to upgrade.

On this page

Primcloud installs the Go SDK your go.mod asks for. Every module project already declares one through the go directive, so most apps need no extra configuration. The version resolves from what's already in the file.

Supported versions#

The Go versions you can install are part of the Primcloud Runtime and move as the Runtime is updated, so there's no fixed version matrix to consult. A new Go patch release becomes installable once the Runtime includes it, which can be some time after the Go project ships it. The build log for each deployment, in the Deployments tab, shows the version that build installed.

Go's own release policy is the practical guide: the Go team supports the two most recent major releases with security fixes. Older majors still build as long as they remain available, but they no longer receive upstream fixes, so move to a current major when you can.

Pinning a version#

Two mechanisms decide which SDK gets installed. In order of precedence:

1. // +heroku goVersion build directive: the most explicit. Add a comment line to go.mod:

go.mod 
module example.com/myapp

// +heroku goVersion =1.26.5
go 1.25

The value accepts standard semver constraints: =, ^, ~, >, <, or a bare version. =1.26.5 pins that exact patch; ^1.26 picks the latest 1.26.x; a bare 1.26 behaves like ^1.26.

2. go directive: used when there's no +heroku goVersion line. This resolves to the latest available patch in the same minor line:

go.mod 
module example.com/myapp

go 1.26

This installs the newest 1.26.x available at build time. Writing go 1.26.0 pins that exact patch instead.

Every module has a go directive, so there's always a version to resolve. There's no third "no configuration" fallback.

Upgrading#

Bump the pin and redeploy:

  • // +heroku goVersion: edit the constraint, commit, push.
  • go directive: edit the value (go 1.25 → go 1.26, say), commit, push.

The next build pulls the newer SDK and caches it from first use. If the upgrade crosses a major-line boundary, expect one longer build while the SDK downloads, then normal speed from the next deploy on.

Bumping the go directive also raises your app's declared minimum Go version, which module consumers see. Bumping only // +heroku goVersion changes what Primcloud builds with, without touching the module's declared minimum.

Read Go's release notes before jumping majors. A newer SDK can surface compile errors in code that built fine on the old one.

When a version is no longer available#

An older Go major stays buildable while it remains in the available set, then eventually drops out. Before that happens:

  • Builds targeting the version keep working while it's still available.
  • Once it's gone, a build that pins the removed version fails with a "Couldn't resolve go version" error.
  • Loosening the constraint (say, =1.20.14 to ^1.20 once 1.20 is gone) won't help; if nothing in that major/minor line is available, resolution still fails. Bump to a supported major.

Move to a current major before your pin drops out, so you're not forced into an upgrade under time pressure.