hashicorp/terraform · error

Error initializing backend %T

Error message

Error initializing backend %T: %s

This is a bug; please report it to the backend developer

What it means

Appended as a diagnostic from `Meta.Backend` when the resolved backend implements `backendrun.CLI` and its `CLIInit(cliOpts)` method returns an error. The message includes the backend's Go type (`%T`) and instructs the user to report it as a bug to the backend developer — because `CLIInit` failing indicates an internal backend defect, not a user-configuration problem (config validation happens earlier).

Solutions

1. Report the bug to the backend developer, including the `%T` type name and the wrapped `%s` detail.
2. If using a local backend, ensure the data/state directories are writable and not locked.
3. Re-run `terraform init` to re-establish backend state cleanly.
4. Upgrade or downgrade the backend / Terraform CLI to a matching known-good version pair.
5. If the backend is `cloud`/`remote` and `CLIInit` fails transiently, retry after confirming HCP Terraform / TFE is reachable.

Example fix

// The backend type in the message identifies which backend has the bug.
// Report to: https://github.com/hashicorp/terraform/issues (for built-in)
// or the backend plugin's own repo.
// Workaround: re-init
terraform init -reconfigure

null

// Detect that a backend opts into CLI init before relying on it.
if _, ok := b.(backendrun.CLI); ok {
    // CLIInit may fail — treat its failure as a backend bug, not user error
}

// CLIInit failures are backend bugs; surface the %T type to the user for reporting.
if err := cli.CLIInit(opts); err != nil {
    return fmt.Errorf("backend %T CLIInit failed (bug): %w", b, err)
}

When it happens

Trigger: The backend passed the type assertion `b.(backendrun.CLI)`, so it opts into CLI initialization. `CLIInit` then fails — e.g. an enhanced backend cannot set up its local state manager, cannot initialize an internal client, or hits an invariant violation. This occurs after `Configure` and `PrepareConfig` already succeeded.

Common situations: A bug in a third-party or custom backend's `CLIInit`; a local backend that cannot create its state storage directory; a cloud backend whose internal client initialization hits an unexpected state after successful config; version skew between Terraform CLI and the backend plugin.

Related errors

• error starting operation
• errInitConfigError
• errInitCopyNotEmpty
• A managed resource address is required. Importing into a…
• at most 1 action can be invoked per operation

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/78b982888530f39f. Report an issue: GitHub.

Appendix: source

Thrown at internal/command/meta_backend.go:179

					fmt.Sprintf(
						"The installed provider plugins are not consistent with the packages selected in the dependency lock file:%s\n\nTerraform uses external plugins to integrate with a variety of different infrastructure services. %s",
						buf.String(), suggestion,
					),
				))
				return nil, diags
			}
		} else {
			// All other errors just get generic handling.
			diags = diags.Append(err)
			return nil, diags
		}
	}
	cliOpts.Validation = true

	// If the backend supports CLI initialization, do it.
	if cli, ok := b.(backendrun.CLI); ok {
		if err := cli.CLIInit(cliOpts); err != nil {
			diags = diags.Append(fmt.Errorf(
				"Error initializing backend %T: %s\n\n"+
					"This is a bug; please report it to the backend developer",
				b, err,
			))
			return nil, diags
		}
	}

	// If the result of loading a backend is an operations backend,
	// then return that as-is. This works even if b == nil (it will be !ok).
	if enhanced, ok := b.(backendrun.OperationsBackend); ok {
		log.Printf("[TRACE] Meta.Backend: backend %T supports operations", b)
		return enhanced, nil
	}

	// We either have a non-operations backend configured for state storage
	// or none configured at all. In either case, we use local as our operations backend
	// and the state-storage backend (if any) to manage state.

View on GitHub (pinned to d32a084675)