🚨 Pulumi Error Guide: 'no resource plugin found' — Install the Missing Provider Plugin

Overview

Pulumi resolves each provider (aws, gcp, kubernetes, random) to a separate resource plugin binary that lives in the plugin cache, not inside your language SDK. When the engine cannot find a plugin whose version satisfies what your program requests, pulumi preview or pulumi up aborts before touching any cloud API:

error: no resource plugin 'aws-v6.0.4' found in the workspace or on your $PATH, install the plugin using `pulumi plugin install resource aws v6.0.4`

You may also see the shorter, unversioned form when no matching plugin is present at all:

error: no resource plugin 'aws' found in the workspace or on your $PATH

The engine is telling you the SDK in your program expects a provider plugin that is not installed in this environment.

Symptoms

• pulumi preview/pulumi up fails immediately, before any resource diff is shown.
• The error names a specific provider and often an exact version (aws-v6.0.4).
• It appears on a fresh clone, a new CI runner, or right after bumping a provider SDK dependency.
• pulumi plugin ls does not list the requested provider, or lists a different version.
• Local machine works but CI fails (the CI plugin cache is empty or not restored).

Common Root Causes

• Plugins were never installed in this workspace — a fresh checkout has the SDK from npm install/pip install but not the provider binary.
• SDK/plugin version mismatch — you upgraded @pulumi/aws (or the pip/go module) but the cached plugin is an older major.
• Empty plugin cache in CI — ~/.pulumi/plugins is not cached between runs, so every job starts with nothing.
• Air-gapped/offline runner — Pulumi cannot download the plugin from the registry on demand.
• Wrong architecture — an arm64 plugin cache on an amd64 runner (or vice versa).
• Custom/dynamic provider not published to the registry and not pinned via pluginDownloadURL.

Diagnostic Workflow

List what plugins are actually installed versus what the program wants:

pulumi plugin ls
pulumi about            # shows host, language runtime, and installed plugins

Read the exact version the engine is asking for from the error, then check the SDK version your program pins:

# Node
npm ls @pulumi/aws
# Python
pip show pulumi-aws
# Go
go list -m all | grep pulumi

Confirm the plugin cache location and whether it is populated:

ls -la ~/.pulumi/plugins
echo "$PULUMI_HOME"      # cache root if overridden

Test connectivity to the plugin registry (rules out air-gapped/proxy issues):

pulumi plugin install resource aws v6.0.4 --reinstall

Example Root Cause Analysis

A team bumped @pulumi/aws from 6.0.0 to 6.0.4 in package.json, merged, and CI failed with no resource plugin 'aws-v6.0.4' found. pulumi plugin ls on the runner showed aws 6.0.0. The CI job cached node_modules (so the new SDK was present) but did not cache ~/.pulumi/plugins, and the runner was offline to the registry through a strict egress proxy.

The SDK requested aws-v6.0.4; the only cached plugin was 6.0.0; the on-demand download to fetch 6.0.4 was blocked. Two fixes together resolved it: an explicit pulumi plugin install resource aws 6.0.4 step (allowed through the proxy), and adding ~/.pulumi/plugins to the CI cache keyed on the lockfile so future runs restore the matching plugin.

Prevention Best Practices

• Add an explicit pulumi plugin install step (or pulumi install) early in CI so plugins are present before preview.
• Cache ~/.pulumi/plugins in CI, keyed on your dependency lockfile, so version bumps invalidate the cache.
• Keep the provider SDK version and any pinned plugin version in lockstep; upgrade them in the same commit.
• For air-gapped runners, pre-seed the plugin cache or host plugins internally and set pluginDownloadURL.
• Match runner architecture to the cached plugins (do not share an arm64 cache with amd64 jobs).
• Run pulumi about in CI diagnostics so a mismatch is visible in logs.

Quick Command Reference

pulumi plugin ls                                   # what is installed
pulumi about                                       # host + plugins + runtime
pulumi plugin install resource aws v6.0.4          # install exact version
pulumi plugin install resource aws v6.0.4 --reinstall
pulumi install                                     # install SDK deps + plugins
npm ls @pulumi/aws                                 # SDK version the program pins
ls -la ~/.pulumi/plugins                           # inspect the plugin cache

Conclusion

no resource plugin found is a provisioning-time dependency error, not a cloud error: your program’s SDK wants a provider plugin binary that this environment does not have. Read the exact version from the message, compare pulumi plugin ls against your SDK pin, and install the matching plugin. Bake plugin installation and cache restoration into CI so the version your SDK requests is always present, and the error disappears for good.