hashicorp/terraform · error

Error parsing %q as a provider address: %w

Error message

Error parsing %q as a provider address: %w

What it means

Thrown by reattach.ParseReattachProviders while iterating the JSON map in the TF_REATTACH_PROVIDERS environment variable: each map key must itself be a valid provider source address. addrs.ParseProviderSourceString rejected the key, so the entry cannot be mapped to an addrs.Provider. This stops all reattach setup because the offending key is uninterpretable.

Source

Thrown at internal/getproviders/reattach/reattach.go:59

		type reattachConfig struct {
			Protocol        string
			ProtocolVersion int
			Addr            struct {
				Network string
				String  string
			}
			Pid  int
			Test bool
		}
		var m map[string]reattachConfig
		err := json.Unmarshal([]byte(in), &m)
		if err != nil {
			return unmanagedProviders, fmt.Errorf("Invalid format for %s: %w", TF_REATTACH_PROVIDERS, err)
		}
		for p, c := range m {
			a, diags := addrs.ParseProviderSourceString(p)
			if diags.HasErrors() {
				return unmanagedProviders, fmt.Errorf("Error parsing %q as a provider address: %w", a, diags.Err())
			}
			var addr net.Addr
			switch c.Addr.Network {
			case "unix":
				addr, err = net.ResolveUnixAddr("unix", c.Addr.String)
				if err != nil {
					return unmanagedProviders, fmt.Errorf("Invalid unix socket path %q for %q: %w", c.Addr.String, p, err)
				}
			case "tcp":
				addr, err = net.ResolveTCPAddr("tcp", c.Addr.String)
				if err != nil {
					return unmanagedProviders, fmt.Errorf("Invalid TCP address %q for %q: %w", c.Addr.String, p, err)
				}
			default:
				return unmanagedProviders, fmt.Errorf("Unknown address type %q for %q", c.Addr.Network, p)
			}
			unmanagedProviders[a] = &plugin.ReattachConfig{
				Protocol:        plugin.Protocol(c.Protocol),

View on GitHub (pinned to c9def3e214)

Solutions

1. Re-read the file:line cited in the error and fix the TF_REATTACH_PROVIDERS JSON key to a valid provider source ("type", "namespace/type", or "hostname/namespace/type").
2. Validate the address with addrs.ParseProviderSourceString in a small Go snippet before exporting the env var.
3. If the process is auto-generated by tf-providershim/exec, regenerate it so the key matches the provider's declared source string.

Example fix

// before
os.Setenv("TF_REATTACH_PROVIDERS", `{"foo/bar/baz/qux": {"Protocol":"grpc"}}`)
// after
os.Setenv("TF_REATTACH_PROVIDERS", `{"registry.terraform.io/hashicorp/foo": {"Protocol":"grpc"}}`)

import "github.com/hashicorp/terraform/internal/addrs"

// Validate every key of the TF_REATTACH_PROVIDERS JSON before setting the env var.
func validateProviderKeys(rawJSON string) error {
    var m map[string]json.RawMessage
    if err := json.Unmarshal([]byte(rawJSON), &m); err != nil {
        return err
    }
    for k := range m {
        if _, diags := addrs.ParseProviderSourceString(k); diags.HasErrors() {
            return fmt.Errorf("invalid provider source key %q: %w", k, diags.Err())
        }
    }
    return nil
}

When it happens

Trigger: Calling ParseReattachProviders (or os.Getenv-based consumers like IsProviderReattached) with TF_REATTACH_PROVIDERS JSON whose top-level object key fails ParseProviderSourceString, e.g. an empty key, a key with more than three slash-separated parts, or characters disallowed in a hostname/namespace/type.

Common situations: Provider developers hand-editing TF_REATTACH_PROVIDERS; a debug build printing the key with extra whitespace or quotes; copying a source string from terraform registry UI that includes a leading '//' or scheme; migrating an old config that used a bare display name with slashes.

Related errors

• Invalid unix socket path %q for %q: %w
• Invalid TCP address %q for %q: %w
• Unknown address type %q for %q
• default workspace not supported You can create a new workspa
• approved using the UI or API

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