What causes "Invalid format for %s: %w" in hashicorp/terraform?

Validate the env var's value with a JSON linter (e.g. `echo "$TF_REATTACH_PROVIDERS" | jq .`) before running Terraform.

Invalid format for %s: %w

Error message

Invalid format for %s: %w

What it means

From ParseReattachProviders. The TF_REATTACH_PROVIDERS environment variable must be a JSON object mapping provider source strings to reattach config objects. json.Unmarshal failing on the raw bytes produces this error, with the underlying JSON error wrapped via %w. Any JSON syntax problem - stray comma, missing brace, wrong types - surfaces here.

Source

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

//
// Calling code is expected to pass in the value of os.Getenv("TF_REATTACH_PROVIDERS")
func ParseReattachProviders(in string) (map[addrs.Provider]*plugin.ReattachConfig, error) {
	unmanagedProviders := map[addrs.Provider]*plugin.ReattachConfig{}
	if in != "" {
		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)
				}

View on GitHub (pinned to c9def3e214)

Solutions

Validate the env var's value with a JSON linter (e.g. `echo "$TF_REATTACH_PROVIDERS" | jq .`) before running Terraform.
Ensure the value is a JSON object whose values match the ReattachConfig shape (Protocol, ProtocolVersion, Addr.Network, Addr.String, Pid, Test).
Fix shell quoting so the whole JSON string is passed intact (single-quote the assignment).
Remove the env var if reattach is not actually needed: unset TF_REATTACH_PROVIDERS.

Example fix

// before (shell)
export TF_REATTACH_PROVIDERS='{"foobar": {"Protocol":"grpc","ProtocolVersion":6,"Pid":12345,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin"},}}'  // trailing comma -> JSON error
// after
export TF_REATTACH_PROVIDERS='{"foobar":{"Protocol":"grpc","ProtocolVersion":6,"Pid":12345,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin"}}}'

Defensive patterns

Strategy: validation

Validate before calling

// Validate the env var JSON before passing it to Terraform.
func validateReattachJSON(in string) error {
    if in == "" { return nil }
    var m map[string]json.RawMessage
    return json.Unmarshal([]byte(in), &m)
}
if err := validateReattachJSON(os.Getenv(reattach.TF_REATTACH_PROVIDERS)); err != nil {
    return fmt.Errorf("TF_REATTACH_PROVIDERS is not valid JSON: %w", err)
}

Try / catch

// Wrap with the env var name so the user knows which input is broken.
providers, err := reattach.ParseReattachProviders(os.Getenv("TF_REATTACH_PROVIDERS"))
if err != nil {
    return fmt.Errorf("cannot start: %w", err)
}

Prevention

Single-quote the env var assignment in shell to preserve the whole JSON string.
Generate TF_REATTACH_PROVIDERS with a JSON encoder, never by hand or string concatenation.
Lint the value with `jq .` before running Terraform.

When it happens

Trigger: ParseReattachProviders(os.Getenv("TF_REATTACH_PROVIDERS")) is called (directly or via IsProviderReattached); the env var is non-empty but json.Unmarshal at line 52 returns an error. Common when the JSON was hand-written, generated by a buggy dev tool, or pasted with smart quotes / trailing commas.

Common situations: Developers using TF_REATTACH_PROVIDERS to debug a provider under development with a malformed JSON blob. Copy-paste from docs introduced smart quotes or missing brackets. A shell quoting bug truncated/escaped the value. An extra trailing comma or a comment (JSON has none).

Related errors

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