🧱 Pulumi Error: Resource Provider Version Mismatch Between Installed and Required Plugin

Exact Error Message

error: could not load plugin for aws provider
'urn:pulumi:prod::app::pulumi:providers:aws::default_6_42_0':
provider version mismatch: program requested "6.42.0" but the workspace has
"6.31.0" installed

warning: resource plugin aws is expected to have version >=6.42.0, but has 6.31.0;
the wrong version may be on your $PATH, or this may be an issue with the plugin

You may also see it as an unexpected diff or panic when a stale plugin serves a resource shape the SDK no longer expects.

What It Means

Every Pulumi program pairs a language SDK (imported in code) with a resource provider plugin binary. The SDK encodes the schema for a specific provider version, and the plugin must serve a compatible version. When the installed plugin version does not satisfy what the SDK requests, Pulumi warns or errors because the two sides can disagree about resource inputs, outputs, and diffing behavior.

Unlike a completely missing plugin, here a plugin is installed — just at the wrong version. Common triggers are a partial upgrade (SDK bumped, plugin not reinstalled), multiple plugin versions in the cache with the wrong one selected, or a globally installed provider on $PATH shadowing the workspace one.

Common Causes

• The provider SDK package was upgraded but pulumi install / pulumi plugin install was not re-run.
• An older provider binary is on $PATH and takes precedence over the workspace plugin cache.
• The lockfile (package-lock.json, go.sum, poetry.lock) pins a newer SDK than the cached plugin.
• CI restored a stale plugin cache from a previous provider version.
• An explicit provider resource pins a version that differs from the default provider version.

Diagnostic Commands

List installed plugins and their versions to spot duplicates or stale entries:

pulumi plugin ls

Find the provider SDK version your program actually pins:

grep -Rn "@pulumi/aws\|pulumi-aws\|Pulumi.Aws" package.json go.mod *.csproj requirements.txt 2>/dev/null

Check whether a provider binary is shadowing the cache on $PATH:

which pulumi-resource-aws

Inspect the exact version each resource requests in state:

pulumi stack export | jq '.deployment.resources[] | select(.type | startswith("pulumi:providers:")) | {type, version}'

Step-by-Step Resolution

1. Reconcile plugins with your SDK dependencies in one step — this installs the versions the program requires:

pulumi install

2. If a specific version is still missing, install it explicitly:

pulumi plugin install resource aws v6.42.0

3. Remove stale plugin versions so the wrong one cannot be selected:

pulumi plugin rm resource aws 6.31.0 --yes

4. If a binary on $PATH is shadowing the workspace plugin, remove or unset it so Pulumi uses its own cache:

which pulumi-resource-aws && echo "remove this from PATH"

5. If an explicit provider resource pins the wrong version, align it in code. For example, in TypeScript:

const aws6 = new aws.Provider("aws6", { region: "us-east-1", version: "6.42.0" });

6. Verify the versions now match, then re-run:

pulumi plugin ls
pulumi preview --stack prod

Prevention

• Always run pulumi install after changing a provider SDK version so the plugin follows the SDK.
• Commit and respect language lockfiles so SDK versions are deterministic across machines and CI.
• Key CI plugin caches on the provider version (or run pulumi install after cache restore) to avoid stale binaries.
• Keep provider binaries out of the global $PATH; let Pulumi manage ~/.pulumi/plugins.
• Bump provider SDK and plugin together in a single reviewed change rather than piecemeal.

Related Errors

• no resource plugin ... found, run pulumi plugin install — the plugin is entirely missing, not just mis-versioned.
• could not load plugin for provider — a broader load failure that a mismatch can trigger.
• unsupported provider plugin protocol version — the plugin is too old/new at the protocol level, not just the semver.
• Diff failed / provider panic — a symptom of a stale plugin serving a mismatched schema.

Frequently Asked Questions

Why does the version matter if the provider name is right? The SDK and plugin share a schema for each version. A version gap can change resource inputs, outputs, and how diffs are computed, so Pulumi refuses to pair mismatched halves rather than risk a wrong or destructive plan.

How do I get the plugin to follow my SDK automatically? Run pulumi install. It reads your project’s SDK dependencies and installs matching plugin versions, keeping both halves aligned without manual version juggling.

Why do I have two versions of the same plugin installed? Pulumi caches each version you have used. That is normal, but a stale one can be selected in edge cases — remove the old one with pulumi plugin rm resource <name> <version> once nothing needs it.

Could a binary on my $PATH be the culprit? Yes. If which pulumi-resource-<name> returns a path, that binary can shadow the workspace cache. Remove it from $PATH so Pulumi uses its managed plugins. Version-alignment checklists live in the prompt library.

Where can I find related fixes? Browse the complete Pulumi guides for more provider and plugin troubleshooting.