🧱 Pulumi Error: 'go.mod file not found' — Go Program Module Init Fix

Exact Error Message

error: failed to load language plugin go: could not run 'go build':
    go: go.mod file not found in current directory or any parent directory;
    see 'go help modules'

error: build of Go program failed

You may also see go: cannot find main module, but found .git/config or go: GO111MODULE=off; import ... : cannot find module providing package. All of these mean the Go toolchain has no module to build from where Pulumi runs your program.

What It Means

For Go projects, Pulumi’s Go language host compiles and runs your program with the standard go toolchain. Modern Go builds require a go.mod file that declares the module path and dependencies. When Pulumi runs go build in your project directory and there is no go.mod in that directory or any parent, the build aborts and Pulumi reports build of Go program failed.

This is a project-scaffolding problem, not a bug in your resource code. It happens most often on a freshly cloned repo, a project created without go mod init, or when Pulumi.yaml points the main at a directory that has no module file.

Common Causes

• The project was never initialized with go mod init, so no go.mod exists.
• go.mod exists somewhere in the repo but not in the directory Pulumi builds (the main in Pulumi.yaml points elsewhere).
• A stray build cache or GO111MODULE=off forces legacy GOPATH mode, so Go ignores modules.
• The repo was cloned but go.mod/go.sum were gitignored or never committed.
• Running pulumi up from the wrong working directory (a parent or sibling folder).
• The Go binary on PATH is too old to support modules or the Pulumi.yaml runtime is misconfigured.

Diagnostic Commands

Confirm whether a go.mod exists and where:

ls -la go.mod
find . -name go.mod

Check what directory and runtime Pulumi is using:

cat Pulumi.yaml

Verify the Go toolchain and module mode:

go version
go env GO111MODULE GOPATH

Reproduce the failing build directly in the project directory:

go build ./...

Step-by-Step Resolution

1. Initialize the module if go.mod is missing. Run this from the directory that contains your Pulumi main.go:

go mod init github.com/your-org/your-project

2. Pull in the Pulumi SDK and provider dependencies, then tidy:

go get github.com/pulumi/pulumi/sdk/v3
go get github.com/pulumi/pulumi-aws/sdk/v6/go/aws
go mod tidy

3. Make sure Pulumi.yaml points at the directory that holds go.mod. For a subdirectory layout, set main explicitly:

name: my-app
runtime:
  name: go
  options:
    binary: ""
main: ./infra

4. Ensure module mode is on if a stale environment disabled it:

go env -w GO111MODULE=on

5. Confirm the program builds on its own before invoking Pulumi:

go build ./...

6. Run the preview from the correct project directory:

cd infra && pulumi preview

If you inherited a Go project and are unsure how the module path and Pulumi.yaml main should line up, a prompt from the Pulumi prompt library can walk through the expected layout.

Prevention

• Always run go mod init (or pulumi new go) when starting a Go Pulumi project so go.mod exists from day one.
• Commit go.mod and go.sum; never gitignore them.
• Keep Pulumi.yaml’s main pointing at the module directory when using a monorepo/subfolder layout.
• Run go build ./... in CI before pulumi preview so missing-module errors fail fast and clearly.
• Avoid setting GO111MODULE=off globally; module mode is the default and expected for Pulumi Go programs.

Related Errors

• failed to load language plugin go (build failure) — a compile error rather than a missing module.
• go: cannot find main module — the same missing-go.mod condition phrased differently.
• cannot find module providing package — a dependency not declared in go.mod; fix with go mod tidy.
• no Pulumi.yaml project file found — you are outside the project directory entirely.

Frequently Asked Questions

Where exactly does the go.mod need to be? In the directory Pulumi builds — the one referenced by main in Pulumi.yaml (the project root by default), or any parent of it.

Do I have to commit go.sum too? Yes; go.sum records dependency checksums and keeps builds reproducible, so commit it alongside go.mod.

Why did it work locally but fail in CI? CI often clones fresh and runs from a different directory; if go.mod was uncommitted or main is wrong, the module is missing in CI.

Can pulumi new go fix an existing project? It scaffolds a new one; for an existing folder, run go mod init and go mod tidy manually instead. For more Go setup guidance, see the Pulumi guides.