🚨 Pulumi Error: 'rpc error: code = Unavailable ... connection refused' — Cause, Fix, and Troubleshooting Guide

Overview

error: rpc error: code = Unavailable desc = connection error ... connection refused means the Pulumi engine tried to talk to a provider plugin over gRPC and the connection was refused. Pulumi runs each provider (aws, gcp, kubernetes, etc.) as a separate subprocess and communicates with it over a local gRPC socket. When that subprocess crashes, fails to start, or exits early, the engine’s next call gets Unavailable / connection refused.

The key insight is that this is a local process failure, not a cloud API outage. The dial tcp: connect: connection refused part refers to the loopback gRPC channel between the CLI and the plugin — the provider process is not listening because it died or never came up.

error: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while
dialing dial tcp: connect: connection refused"

Symptoms

• pulumi up or pulumi preview fails partway through with code = Unavailable and connection refused.
• The failure often follows a burst of resource operations rather than at the very start.
• Re-running sometimes gets further before failing again, suggesting a crash under load.
• dmesg/system logs show the provider binary was killed (segfault or OOM).
• A custom dynamic provider or a locally built provider is in the stack.

Common Root Causes

1. The provider subprocess crashed

The plugin hit a panic, segfault, or unhandled error and exited. The engine’s next gRPC call then finds nothing listening.

transport: Error while dialing dial tcp: connect: connection refused

2. The provider was killed by the OS (out of memory)

Large stacks with many concurrent operations can push a provider’s memory past the host limit; the kernel OOM-killer terminates it and the socket disappears.

3. Too much parallelism overwhelming the provider or the host

The default parallelism spins up many concurrent provider calls. On small CI runners this can exhaust memory or file descriptors and take the provider down.

4. A broken or mismatched provider plugin binary

A corrupted download, a wrong-architecture binary, or a provider/SDK version mismatch can cause the process to start and immediately exit, refusing subsequent connections.

5. A crashing dynamic/custom provider

Custom providers (dynamic providers, or a provider you built) that throw during Create/Update can bring the process down, surfacing as Unavailable to the engine.

How to Diagnose

Turn on gRPC debug logging to see exactly which provider call failed and capture the plugin’s own output:

PULUMI_DEBUG_GRPC="$(pwd)/grpc.log" \
  pulumi up --logtostderr -v=9 2> pulumi-debug.log

Inspect the plugin log and engine log for a panic, stack trace, or the last successful RPC before the refusal:

grep -iE "panic|signal|killed|Unavailable" pulumi-debug.log

Check the host for an OOM kill of the provider process:

dmesg -T | grep -i -E "killed process|out of memory|oom"

List installed plugins and versions to rule out a bad binary:

pulumi plugin ls

Fixes

Reduce parallelism so the provider and host aren’t overwhelmed. This is the most reliable fix for OOM/crash-under-load cases:

pulumi up --parallel 1
# or a moderate value on larger hosts
pulumi up --parallel 4

Give the process more memory (or a bigger runner). On CI, bump the runner size or free memory before the run; providers holding large plans need headroom. Lowering --parallel also cuts peak memory.

Reinstall the provider plugin if the binary is corrupt or mismatched:

pulumi plugin rm resource aws --all --yes
pulumi plugin install resource aws <version>
# or simply re-run; Pulumi reinstalls the version your SDK requires

Retry the operation. Because state from completed steps is persisted, re-running resumes from where it failed:

pulumi up

If a pending operations warning appears after the crash, resolve it before continuing.

Fix a crashing custom/dynamic provider. Read the panic/stack trace from the debug log, add error handling in the provider’s Create/Update/Read methods so it returns a gRPC error instead of exiting, and rebuild it.

Update the CLI and providers to compatible versions. A provider/SDK skew can destabilize the subprocess:

pulumi version
pulumi plugin ls
# align SDK (package.json / requirements.txt / go.mod) with plugin versions, then reinstall

What to Watch Out For

• code = Unavailable here is a local plugin failure, not a cloud API outage — check the plugin, not your network to AWS/GCP.
• After a mid-run crash, watch for pending operations; clear them before the next update.
• --parallel 1 is slower but often the difference between a green and red run on constrained CI.
• Set PULUMI_DEBUG_GRPC to a file to keep the gRPC transcript — it names the failing provider and method.
• Repeated OOM kills point at host memory limits, not Pulumi; scale the runner or split the stack.

Related Guides

• Pulumi Error: ‘transport is closing’ — Troubleshooting Guide
• Pulumi Error: ‘could not load plugin’ — Troubleshooting Guide
• Pulumi Error: ‘pending operations’ — Troubleshooting Guide