🚨 Pulumi Error: 'could not load plugin for aws provider' — Cause, Fix, and Troubleshooting Guide

Overview

error: could not load plugin for aws provider means Pulumi found a provider plugin binary but could not start it. This is different from no resource plugin found, where the binary is simply missing. Here the file exists on disk, Pulumi tried to exec it as a gRPC subprocess, and the process failed to launch or handshake — typically because the binary is corrupt, truncated from a bad download, built for the wrong CPU architecture or OS, or lacks execute permission.

The failure usually carries an OS-level cause:

error: could not load plugin for aws provider: fork/exec /root/.pulumi/plugins/resource-aws-v6.40.0/pulumi-resource-aws: exec format error

Other variants you will see:

error: could not load plugin for aws provider: fork/exec .../pulumi-resource-aws: permission denied
error: could not load plugin for aws provider: unexpected EOF
error: could not load plugin for aws provider: could not read plugin ... : unexpected end of file

The tell is the underlying reason after the colon — exec format error, permission denied, unexpected EOF — all point at the binary itself, not at your program or config.

Symptoms

• pulumi up / pulumi preview fails immediately with could not load plugin for aws provider.
• The message includes an OS exec error: exec format error, permission denied, unexpected EOF, or text file busy.
• The plugin is listed by pulumi plugin ls (so it is not “missing”), yet still fails.
• Common right after moving a project between architectures (x86_64 → arm64), inside a Docker image built for a different platform, or after an interrupted pulumi plugin install.
• Works on one machine/CI runner but not another with a different CPU or OS.

Common Root Causes

1. Wrong CPU architecture or OS

The plugin binary is amd64 but the host is arm64 (Apple Silicon, Graviton, arm CI), or a Linux binary landed in a container built FROM a different platform. The kernel refuses to exec it.

exec format error

2. Truncated or corrupt download

A network interruption during pulumi plugin install (or a Docker layer cache) left a partial binary. Pulumi execs it and the gRPC handshake dies.

unexpected EOF

3. Missing execute permission

The binary was restored from a tar/zip or copied into an image without the execute bit, or onto a filesystem mounted noexec.

permission denied

4. Plugin cache baked into the wrong image layer

A Dockerfile copies ~/.pulumi/plugins from a build stage on a different base image, mixing glibc/musl or architecture.

5. Version/protocol mismatch with the Pulumi CLI

A very old plugin binary paired with a much newer CLI (or vice versa) can fail the plugin handshake even though the file is intact.

How to Diagnose

Confirm what Pulumi has cached and where:

pulumi plugin ls
ls -la ~/.pulumi/plugins/resource-aws-v6.40.0/

Check the architecture of the binary against the host:

file ~/.pulumi/plugins/resource-aws-v6.40.0/pulumi-resource-aws
uname -m

If file reports x86-64 while uname -m reports aarch64, that is your exec format error.

Verify the binary is executable and can even start:

~/.pulumi/plugins/resource-aws-v6.40.0/pulumi-resource-aws --help

A healthy plugin prints usage/version. exec format error or permission denied here confirms the binary, not Pulumi, is the problem.

Check filesystem mount options if you suspect noexec:

mount | grep -E "$(df ~/.pulumi/plugins | tail -1 | awk '{print $6}')"

Fixes

All causes — the reliable reset: remove the bad plugin and reinstall it for the current platform.

pulumi plugin rm resource aws --all --yes
pulumi plugin install resource aws 6.40.0

Cause 1 — wrong arch/OS: Reinstall on the target platform (do not copy the cache across architectures). In multi-arch Docker builds, install plugins in the final stage that matches the runtime platform, or set the platform explicitly:

docker build --platform linux/arm64 -t myapp .

Cause 2 — truncated download: Delete the partial plugin and reinstall (commands above). If installs are flaky in CI, add a checksum/retry around the install step and avoid caching a half-written plugin dir.

Cause 3 — permission denied: Restore the execute bit, or move the plugin dir off a noexec mount.

chmod +x ~/.pulumi/plugins/resource-aws-v6.40.0/pulumi-resource-aws

Cause 4 — Docker layering: Run pulumi plugin install inside the same image/stage that runs Pulumi, so the binary matches the base image and architecture. Do not COPY a plugin cache from an unrelated build stage.

Cause 5 — version mismatch: Align the plugin version with a CLI-compatible release. Reinstall the version your Pulumi.yaml/lockfile expects, or upgrade the CLI:

pulumi version
pulumi plugin install resource aws 6.40.0

What to Watch Out For

• could not load plugin (binary won’t start) is not the same as no resource plugin found (binary absent) — the fix differs, so read the exact wording.
• Never copy ~/.pulumi/plugins between machines of different architecture or libc; reinstall instead.
• In Docker, install plugins in the runtime stage and pin --platform to avoid silent arch mismatches.
• Keep plugin installs out of layers that get cached across base-image changes.
• Mount the Pulumi home on an exec-capable filesystem in locked-down CI environments.
• Pin provider versions in Pulumi.yaml so every runner installs an identical, CLI-compatible binary.

Related Guides

• Pulumi Error: ‘no resource plugin found’ — Troubleshooting Guide
• Pulumi Error: ‘resource already exists’ — Troubleshooting Guide
• IaC Testing Strategies That Actually Work