produce a better error message when the stored backend configuration is corrupted

[AleksandrSor]

Terraform Version

v1.14.0

Terraform Configuration Files

terraform {
  backend "local" {
    path = ".terraform/terraform.tfstate"
  }
}

data "aws_ami" "al2023" {
  most_recent = true

  filter {
    name   = "architecture"
    values = ["x86_64"]
  }

  filter {
    name   = "manifest-location"
    values = ["amazon/al2023-ami-2023.*"] # al2023-ami-ecs-hvm-2023.* for ecs images
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }

  filter {
    name   = "image-type"
    values = ["machine"]
  }

  owners = ["amazon"] # Amazon
}

output "aws_ami_id" {
  description = "ID of the EC2 instance"
  value       = data.aws_ami.al2023.id
}

Debug Output

$ terraform init
2025-12-01T10:37:44.808Z [INFO]  Terraform version: 1.14.0
2025-12-01T10:37:44.808Z [DEBUG] using github.com/hashicorp/go-tfe v1.94.0
2025-12-01T10:37:44.808Z [DEBUG] using github.com/hashicorp/hcl/v2 v2.24.0
2025-12-01T10:37:44.808Z [DEBUG] using github.com/hashicorp/terraform-svchost v0.1.1
2025-12-01T10:37:44.808Z [DEBUG] using github.com/zclconf/go-cty v1.16.3
2025-12-01T10:37:44.808Z [INFO]  Go runtime version: go1.25.4
2025-12-01T10:37:44.808Z [INFO]  CLI args: []string{"terraform", "init"}
2025-12-01T10:37:44.808Z [TRACE] Stdout is a terminal of width 229
2025-12-01T10:37:44.808Z [TRACE] Stderr is a terminal of width 229
2025-12-01T10:37:44.808Z [TRACE] Stdin is a terminal
2025-12-01T10:37:44.808Z [DEBUG] Attempting to open CLI config file: /home/vscode/.terraformrc
2025-12-01T10:37:44.808Z [DEBUG] File doesn't exist, but doesn't need to. Ignoring.
2025-12-01T10:37:44.809Z [DEBUG] ignoring non-existing provider search directory terraform.d/plugins
2025-12-01T10:37:44.809Z [DEBUG] ignoring non-existing provider search directory /home/vscode/.terraform.d/plugins
2025-12-01T10:37:44.809Z [DEBUG] ignoring non-existing provider search directory /home/vscode/.local/share/terraform/plugins
2025-12-01T10:37:44.809Z [DEBUG] ignoring non-existing provider search directory /usr/local/share/terraform/plugins
2025-12-01T10:37:44.809Z [DEBUG] ignoring non-existing provider search directory /usr/share/terraform/plugins
2025-12-01T10:37:44.809Z [INFO]  CLI command args: []string{"init"}
Initializing the backend...
2025-12-01T10:37:44.809Z [TRACE] Meta.Backend: built configuration for "local" backend with hash value 4294472279
╷
│ Error: Failed to load state: unsupported backend state version 4; you may need to use Terraform CLI v1.14.0 to work in this directory
│ 
│ 
╵

Expected Behavior

work normally

Actual Behavior

not wotking after state initially saved with

terraform apply

Steps to Reproduce

terraform init
terraform apply

and after everything ok and state saved
any farther operations generate an error

Additional Context

No response

References

No response

Generative AI / LLM assisted development?

No response

[AleksandrSor]

terraform.tfstate.zip
state created initially
seems ok

[AleksandrSor]

Workaround
So noticed if you declare backend "local" even wo any parameters cli creates file ".terraform/terraform.tfstate" version 3 and terraform.tfstate version 4 in supposed to be a state location
It does not happened if you do not declare backend "local" in config

terraform {
  backend "local" {
  }
}

so do not use ".terraform/terraform.tfstate" in a path
this works

terraform {
  backend "local" {
    path = ".terraform/local.tfstate"
  }
}

[jbardin]

Hi @AleksandrSor,

The .terraform/ directory is private to the Terraform process, has no real guarantee of stability, and should not be used for user data. You are overwriting some internal state for the cli making it invalid, so Terraform is guessing that the running CLI is out of date when it can't decode the stored backend config.