hashicorp/terraform · error

Migrating state from HCP Terraform or Terraform Enterprise t

Error message

Migrating state from HCP Terraform or Terraform Enterprise to another backend is not 
yet implemented.

Please use the API to do this: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions

What it means

Returned by backendMigrateTFC (meta_backend_migrate.go:594) when the source backend is *cloud.Cloud (HCP Terraform / Terraform Enterprise) and the destination is a non-cloud backend. Terraform cannot migrate state OUT of HCP Terraform via the CLI; it returns errTFCMigrateNotYetImplemented pointing to the state-versions API. This is a hard limitation, not a config typo.

Source

Thrown at internal/command/meta_backend_migrate.go:594

	_, sourceTFC := opts.Source.(*cloud.Cloud)
	cloudBackendDestination, destinationTFC := opts.Destination.(*cloud.Cloud)

	sourceWorkspaces, sourceSingleState, err := retrieveWorkspaces(opts.Source, opts.SourceType)
	if err != nil {
		return err
	}
	//to be used below, not yet implamented
	// destinationWorkspaces, destinationSingleState
	_, _, err = retrieveWorkspaces(opts.Destination, opts.SourceType)
	if err != nil {
		return err
	}

	// from HCP Terraform to non-TFC backend
	if sourceTFC && !destinationTFC {
		// From HCP Terraform to another backend. This is not yet implemented, and
		// we recommend people to use the HCP Terraform API.
		return errors.New(strings.TrimSpace(errTFCMigrateNotYetImplemented))
	}

	// Everything below, by the above two conditionals, now assumes that the
	// destination is always HCP Terraform.
	sourceSingle := sourceSingleState || (len(sourceWorkspaces) == 1)
	if sourceSingle {
		if cloudBackendDestination.WorkspaceMapping.Strategy() == cloud.WorkspaceNameStrategy {
			// If we know the name via WorkspaceNameStrategy, then set the
			// destinationWorkspace to the new Name and skip the user prompt. Here the
			// destinationWorkspace is not set to `default` thereby we will create it
			// in HCP Terraform if it does not exist.
			opts.destinationWorkspace = cloudBackendDestination.WorkspaceMapping.Name
		}

		currentWorkspace, err := m.Workspace()
		if err != nil {
			return err
		}

View on GitHub (pinned to c9def3e214)

Solutions

1. Use the HCP Terraform State Versions API (https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions) to download current state, then `terraform state push` it into the new backend.
2. Download the state JSON via the TFC UI 'Current state' / API, save as terraform.tfstate, configure the new backend, run `terraform init -reconfigure`, then `terraform state push terraform.tfstate`.
3. Confirm the source really must be cloud; if the migration direction is reversed (non-cloud -> cloud) it is supported and this error will not occur.

Example fix

# before: cloud -> s3 triggers not-yet-implemented
 # (edit backend block cloud{} -> backend "s3" {})
 terraform init
# after: export then push
 # 1. download state JSON from TFC API/UI -> tf.tfstate
 terraform init -reconfigure        # point at s3, discard old
 terraform state push tf.tfstate

// Detect the unsupported direction BEFORE running init.
 if sourceBackendIsCloud(cfg) && !destBackendIsCloud(newCfg) {
     // export state via TFC API, then state push into the new backend
     return errors.New("cloud->non-cloud migration unsupported; use API + terraform state push")
 }

When it happens

Trigger: Changing a backend block from `cloud {}` (or the legacy `remote {}`) to `backend "s3"` / `backend "local"` / etc. and running `terraform init` which triggers backendMigrateTFC.

Common situations: Team moving off HCP Terraform to a self-managed backend; consolidating from TFC to local for a sandbox; mistaken backend block edit.

Related errors

• can't show a saved cloud plan unless the current root module
• Can't ask approval for state migration when interactive inpu
• error: using a saved cloud plan when executing Terraform loc
• Failed to get existing workspaces: %s
• Couldn't create initial workspace: %w

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