Attempted to initialize pluggable state with a nil provider

Error message

Attempted to initialize pluggable state with a nil provider interface. This is a bug in Terraform and should be reported

What it means

Returned by NewPluggable (internal/backend/pluggable/pluggable.go:38) when the providers.Interface argument p is nil. Pluggable wraps an already-configured provider to expose its state store via the backend.Backend interface; a nil provider cannot service any gRPC call. The message explicitly states this is a bug in Terraform, not a user/config error.

Source

Thrown at internal/backend/pluggable/pluggable.go:38

// NewPluggable returns a Pluggable. A Pluggable fulfils the
// backend.Backend interface and allows management of state via
// a state store implemented in the provider that's within the Pluggable.
//
// These are the assumptions about that
// provider:
// * The provider implements at least one state store.
// * The provider has already been fully configured before using NewPluggable.
//
// The state store could also be configured prior to using NewPluggable,
// but preferably it will be configured via the Pluggable,
// using the relevant backend.Backend methods.
//
// By wrapping a configured provider in a Pluggable we allow calling code
// to use the provider's gRPC methods when interacting with state.
func NewPluggable(p providers.Interface, typeName string) (*Pluggable, error) {
	if p == nil {
		return nil, errors.New("Attempted to initialize pluggable state with a nil provider interface. This is a bug in Terraform and should be reported")
	}
	if typeName == "" {
		return nil, errors.New("Attempted to initialize pluggable state with an empty string identifier for the state store. This is a bug in Terraform and should be reported")
	}

	return &Pluggable{
		provider: p,
		typeName: typeName,
	}, nil
}

var _ backend.Backend = &Pluggable{}

type Pluggable struct {
	provider providers.Interface
	typeName string
}

View on GitHub (pinned to c9def3e214)

Solutions

Report the bug to the Terraform maintainers with the full log and stack trace, as the message instructs.
Upgrade or downgrade Terraform to a known-good version (this is a core invariant bug, not config).
Check that your provider plugin actually started (plugin handshake logs) — a crashed provider can surface as nil upstream.

Defensive patterns

Strategy: validation

Validate before calling

// Guard the constructor precondition at the call site.
if p == nil {
    return nil, fmt.Errorf("cannot build pluggable backend: provider is nil (upstream provider error)")
}
return pluggable.NewPluggable(p, typeName)

Try / catch

pb, err := pluggable.NewPluggable(p, typeName)
if err != nil {
    // This is an internal bug; report it rather than retrying.
    return fmt.Errorf("internal terraform error: %w", err)
}

Prevention

Always check provider factory errors before forwarding the provider to NewPluggable.
Treat a nil provider with a non-nil error from the factory as fatal.
Report these as bugs; do not build retry logic around internal invariants.

When it happens

Trigger: Internal Terraform code calling NewPluggable(nil, typeName) because provider instantiation failed earlier and the nil was not guarded before reaching this constructor. It is a programmer/invariant violation in the terraform binary itself.

Common situations: A regression in terraform core where provider factory returns nil on error and the caller forwards it; a faulty custom build; an edge case during provider plugin crash/handshake that yields a nil interface despite no error.

Related errors

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/374518c3aa18ca16. Report an issue: GitHub.