🧱 Pulumi Error: 'failed to load language plugin go' Go Toolchain/Build Failure

Exact Error Message

error: failed to load language plugin go: could not read plugin
    [/home/dev/.pulumi/bin/pulumi-language-go] stdout: EOF

error: go inline source runtime error, an assembly of your Pulumi program failed:
    go build -o /tmp/pulumi-go.XXXX .: exit status 1
# example.com/infra
./main.go:23:14: undefined: ec2.NewInstanc
error: an unhandled error occurred: program exited with non-zero exit code: 1

You may also see go: command not found, go.mod file not found in current directory or any parent directory, or a compiler error listing the exact .go file and line — all of them stop Pulumi before any resource is created.

What It Means

For a Go project, Pulumi’s pulumi-language-go plugin compiles your program with the Go toolchain and then runs the resulting binary. Unlike interpreted languages, a Go Pulumi program must build successfully first. If go is not installed, the module is misconfigured, or the code does not compile, the language host reports a build failure and Pulumi aborts.

Because the failure comes from go build, the message usually contains a normal Go compiler error (undefined symbol, missing import, type mismatch). That is your real signal: fix the compile error and the plugin loads.

Common Causes

• The Go toolchain is not installed or not on PATH for the shell/CI that runs pulumi.
• A genuine compile error in the program — a typo, wrong SDK function name, or type mismatch.
• go.mod is missing, or the module path/dependencies are out of sync (needs go mod tidy).
• The installed Go version is older than the go directive required in go.mod or by the Pulumi SDK.
• A stale build cache or an unresolved require for github.com/pulumi/pulumi-<provider>/sdk.

Diagnostic Commands

Confirm the toolchain is present and new enough:

go version

Verify the module resolves and compiles on its own — this is what the language host does internally:

go build ./...

Sync module requirements and remove unused ones:

go mod tidy

Check that the Pulumi SDK and provider SDKs are actually required:

grep -E "pulumi" go.mod

Run Pulumi with maximum verbosity to see the exact go build command and its output:

pulumi preview --logtostderr -v=9 2>pulumi.log

Step-by-Step Resolution

1. Read the compiler error at the bottom of the message first. If it names a file and line (./main.go:23:14: undefined: ...), that is the fix — correct the symbol or import and move on.

2. If you see go: command not found, install Go and make sure it is on PATH:

go version || echo "install Go from https://go.dev/dl and add it to PATH"

3. If you see go.mod file not found, initialise the module at the project root:

go mod init example.com/infra

4. Resolve and download dependencies, including the Pulumi SDKs:

go mod tidy
go mod download

5. Build the program yourself to reproduce and clear the error outside Pulumi:

go build ./...

6. If the toolchain is too old for the go directive in go.mod, upgrade Go (or lower the directive to match your installed version) until go build succeeds.

7. Re-run the Pulumi operation once the build is clean:

pulumi preview

Previewing update (dev)
     Type                 Name         Plan
 +   pulumi:pulumi:Stack  infra-dev

Prevention

• Commit go.mod and go.sum, and run go mod tidy before every push so dependency drift never reaches CI.
• Pin the Go version in CI (and in the go directive) so a runner upgrade does not silently break the build.
• Add a go build ./... (or go vet ./...) step to CI before pulumi up to catch compile errors early with a faster feedback loop.
• Keep provider SDK versions (pulumi-aws/sdk, etc.) aligned with the plugin versions you install.
• Do not commit compiled binaries or a populated GOCACHE; let each environment build from source.

Related Errors

• go.mod file not found — a missing module init, a common precursor to this failure covered in its own guide.
• failed to load language plugin python — the same class of language-host failure for a Python project.
• no resource plugin 'aws' found — a missing provider plugin, fixed with pulumi plugin install, not a build problem.
• undefined: <symbol> from go build — a plain Go compile error surfaced through Pulumi.

Frequently Asked Questions

Why does Pulumi compile my Go program at all? Go is a compiled language, so pulumi-language-go runs go build and executes the binary; any compile error becomes a language-plugin load failure.

How do I see the underlying build error? Run pulumi preview --logtostderr -v=9, or simply run go build ./... yourself — Pulumi reports the identical compiler output.

It works on my laptop but fails in CI — why? The runner usually has a different or missing Go toolchain, so pin the Go version in CI and run go mod download before pulumi up.

The error mentions the go directive version — what do I change? Either upgrade the installed Go toolchain to satisfy the go 1.x directive in go.mod, or lower the directive to match the version you actually run. For ready-made prompts that diagnose Go build and module errors, see the Pulumi prompt library.

Where are more guides like this? Browse the full Pulumi guides for language-host, provider, and state troubleshooting.