🧱 Pulumi Error: 'unknown provider type' Provider Plugin Not Installed

Exact Error Message

error: could not load plugin for aws provider 'urn:pulumi:dev::myproj::pulumi:providers:aws::default':
    unknown provider type 'aws'

error: could not read plugin [pulumi-resource-aws] : no resource plugin 'aws'
    found in the workspace or on your $PATH, install the plugin using
    `pulumi plugin install resource aws`

You may also see provider of unknown type "gcp" or Could not automatically download and install resource plugin 'pulumi-resource-azure-native'. All mean the same thing: Pulumi needs a provider plugin it cannot find.

What It Means

Every cloud resource in Pulumi is backed by a resource provider plugin — a separate binary such as pulumi-resource-aws that Pulumi launches to create, read, and diff resources of that type. Your program’s SDK (pulumi_aws, @pulumi/aws, etc.) generates resource definitions, but the actual plumbing lives in the provider plugin, which is downloaded and cached under ~/.pulumi/plugins.

An “unknown provider type” error means Pulumi encountered a resource whose provider plugin is not installed and could not be auto-acquired. This is common on fresh CI runners, in air-gapped environments, or when the SDK version does not carry a matching plugin version to auto-download.

Common Causes

• The provider plugin was never installed and auto-download is disabled or blocked (offline/air-gapped, proxy, or PULUMI_SKIP_UPDATE_CHECK/policy settings).
• A fresh machine or CI runner has an empty ~/.pulumi/plugins cache.
• The SDK version in your program does not pin a plugin version, so Pulumi cannot decide what to fetch.
• A network/registry failure prevented the automatic plugin download during pulumi up.
• An explicit provider resource references a provider whose plugin is absent.

Diagnostic Commands

List the provider plugins Pulumi currently has installed:

pulumi plugin ls

Check which provider SDK versions your program depends on (Python example):

pip show pulumi-aws | grep -E "Name|Version"

For a TypeScript project:

cat package.json | grep "@pulumi/"

Run a preview with verbose logging to see the exact provider type and version Pulumi tries to resolve:

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

Step-by-Step Resolution

1. Confirm the missing provider from the error (unknown provider type 'aws') and check whether it is installed:

pulumi plugin ls

2. Install the provider plugin explicitly. If you know the version your SDK expects, pin it:

pulumi plugin install resource aws v6.66.0

Omit the version to let Pulumi pick the latest compatible plugin:

pulumi plugin install resource aws

3. If your project declares plugins in Pulumi.yaml or via SDK versions, let Pulumi install everything the project needs in one step:

pulumi install

4. In an air-gapped or proxied environment, point Pulumi at your internal mirror so the download can succeed:

export PULUMI_PLUGIN_DOWNLOAD_URL="https://artifacts.internal/pulumi-plugins"
pulumi plugin install resource aws v6.66.0

5. Verify the plugin now resolves:

pulumi plugin ls | grep aws

NAME  KIND      VERSION  SIZE
aws   resource  6.66.0   412 MB

6. Re-run the operation:

pulumi preview

7. If it still fails, ensure the SDK version and the installed plugin version are compatible — a large mismatch can leave Pulumi unable to map resource types.

Prevention

• Run pulumi install as the first step of every CI job so the plugin cache is populated before pulumi up.
• Pin provider SDK versions in requirements.txt/package.json/go.mod so the plugin version Pulumi auto-downloads is deterministic.
• Cache ~/.pulumi/plugins between CI runs to avoid re-downloading large provider binaries every time.
• In air-gapped setups, mirror provider plugins to an internal artifact store and set PULUMI_PLUGIN_DOWNLOAD_URL.
• Keep SDK upgrades and plugin installs in the same change so versions never drift apart.

Related Errors

• no resource plugin 'aws' found ... run pulumi plugin install — the explicit install prompt, covered in its own guide.
• resource provider version mismatch — the plugin is present but its version differs from what the SDK requires.
• failed to load language plugin python — a language host failure, distinct from a missing resource provider.
• invalid provider configuration — the plugin loads but a required provider argument is missing.

Frequently Asked Questions

Doesn’t Pulumi download providers automatically? Usually yes, during pulumi up, but auto-download fails in air-gapped or proxied environments and when the SDK does not pin a resolvable plugin version, which produces this error.

How do I know which plugin version to install? Match it to your provider SDK version — check pip show pulumi-aws or package.json, then pulumi plugin install resource aws vX.Y.Z.

Why does CI hit this but my laptop does not? Your laptop already has the plugin cached under ~/.pulumi/plugins, while a fresh runner starts empty; run pulumi install in CI and cache that directory.

How do I install providers behind a firewall? Set PULUMI_PLUGIN_DOWNLOAD_URL to an internal mirror that hosts the provider binaries, then run pulumi plugin install. For prompts that map SDK versions to the right plugin installs, see the Pulumi prompt library.

Where are more provider guides? Browse the full Pulumi guides for plugin, version-mismatch, and configuration issues.