What causes "unknown provider '%v' -> '%v'" in pulumi/pulumi?

Register the provider in the same stack and pass the Provider resource object directly

unknown provider '%v' -> '%v'

Error message

unknown provider '%v' -> '%v'

What it means

After resolving a provider reference, `getProviderFromSource` looks it up in the provider source (`providerSource.GetProvider(providerRef)`). If no provider instance with that exact reference (package, type, name, ID) has been registered in this deployment, it fails with `unknown provider '<raw>' -> '<resolved ref>'`, showing both the raw and canonical reference.

Source

Thrown at pkg/resource/deploy/source_eval.go:750

// getProviderFromSource fetches the provider plugin for a resource, read, or invoke from the given
// package with the given unparsed provider reference. If the unparsed provider reference is empty,
// this function returns the plugin for the indicated package's default provider.
func (rm *resmon) getProviderFromSource(
	providerSource ProviderSource, defaultProviders *defaultProviders,
	req providers.ProviderRequest, rawProviderRef string,
	token tokens.ModuleMember,
) (plugin.Provider, error) {
	providerRef, err := rm.getProviderReference(defaultProviders, req, rawProviderRef)
	if err != nil {
		return nil, fmt.Errorf("getProviderFromSource: %w", err)
	} else if sdkproviders.IsDenyDefaultsProvider(providerRef) {
		msg := diag.GetDefaultProviderDenied("Invoke").Message
		return nil, fmt.Errorf(msg, req.Package(), token)
	}

	provider, ok := providerSource.GetProvider(providerRef)
	if !ok {
		return nil, fmt.Errorf("unknown provider '%v' -> '%v'", rawProviderRef, providerRef)
	}
	return provider, nil
}

func parseProviderRequest(
	pkg tokens.Package, version,
	pluginDownloadURL string, pluginChecksums map[string][]byte,
	parameterization *workspace.Parameterization,
) (providers.ProviderRequest, error) {
	if version == "" {
		logging.V(5).Infof("parseProviderRequest(%s): semver version is the empty string", pkg)
		return providers.NewProviderRequest(pkg, nil, pluginDownloadURL, pluginChecksums, parameterization), nil
	}

	parsedVersion, err := semver.Parse(version)
	if err != nil {
		logging.V(5).Infof("parseProviderRequest(%s, %s): semver version string is invalid: %v", pkg, version, err)
		return providers.ProviderRequest{}, err

View on GitHub (pinned to 793f7b2e16)

Solutions

Register the provider in the same stack and pass the Provider resource object directly
If cross-stack, export the provider as a stack output and use a Provider resource constructed from it, not a raw ID reference
Ensure the provider resource name matches what resources reference; remove stale references after renames
Run `pulumi stack output` / inspect state (`pulumi stack export`) to find valid provider URNs

Example fix

// before (TS)
const bucket = new aws.s3.Bucket("b", {}, { provider: "aws::Provider::old::ABC..." });
// after
const awsProvider = new aws.Provider("prov");
const bucket = new aws.s3.Bucket("b", {}, { provider: awsProvider });

Defensive patterns

Strategy: validation

Validate before calling

// TS: before wiring a cross-stack provider, export and verify it
// stack A: export const providerUrn = provider.urn;
// stack B:
const ref = new pulumi.StackReference("org/proj/stackA");
const urn = await ref.getOutputValue("providerUrn");
if (!urn || typeof urn !== 'string') throw new Error('provider not exported from source stack');

Type guard

function looksLikeProviderUrn(v: unknown): v is string {
  return typeof v === 'string' && /::Provider::/.test(v) && /[a-z0-9]{26}$/.test(v);
}

Try / catch

// TS automation API
try {
  await stack.up();
} catch (err) {
  if (String(err).includes("unknown provider")) {
    console.error("Referenced provider is not registered in this stack; register it locally");
  }
  throw err;
}

Prevention

Reference providers via Provider resource objects created in the same stack
After renaming/removing a provider resource, update all resources referencing it
For cross-stack needs, export the provider and reconstruct it, don't copy raw IDs
Run a preview to catch dangling provider references before real deployments

When it happens

Trigger: Passing an explicit provider reference to RegisterResource/Invoke whose provider resource was never registered in the current deployment — e.g. referencing a provider from another stack, a deleted provider, or a typo'd name/ID.

Common situations: Cross-stack provider reuse via `stackReference` without exporting the full provider; provider resource removed/renamed in code while other resources still reference the old URN; copied code referencing provider IDs that don't exist in this stack.

Related errors

AI-assisted analysis of pulumi/pulumi@793f7b2e16 (2026-08-31). Data as JSON: /api/errors/f97ca690f6f2293d. Report an issue: GitHub.