{"record":{"id":"a0295393b53a78ba","repo":"hashicorp/terraform","slug":"invalid-syntax-no-format-version-number","errorCode":null,"errorMessage":"invalid syntax: no format version number","messagePattern":"invalid syntax: no format version number","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/workdir/backend_state.go","lineNumber":90,"sourceCode":"\t// the format, we'll do a first pass of decoding just the \"version\"\n\t// property, and then decode the rest only if we find the version number\n\t// that we're expecting.\n\ttype VersionSniff struct {\n\t\tVersion   int    `json:\"version\"`\n\t\tTFVersion string `json:\"terraform_version,omitempty\"`\n\t}\n\tvar versionSniff VersionSniff\n\terr := json.Unmarshal(src, &versionSniff)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"invalid syntax: %w\", err)\n\t}\n\tif versionSniff.Version == 0 {\n\t\t// This could either mean that it's explicitly \"version\": 0 or that\n\t\t// the version property is missing. We'll assume the latter here\n\t\t// because state snapshot version 0 was an encoding/gob binary format\n\t\t// rather than a JSON format and so it would be very weird for\n\t\t// that to show up in a JSON file.\n\t\treturn nil, fmt.Errorf(\"invalid syntax: no format version number\")\n\t}\n\tif versionSniff.Version != 3 {\n\t\treturn nil, fmt.Errorf(\"unsupported backend state version %d; you may need to use Terraform CLI v%s to work in this directory\", versionSniff.Version, versionSniff.TFVersion)\n\t}\n\n\t// If we get here then we can be sure that this file at least _thinks_\n\t// it's format version 3.\n\tvar stateFile BackendStateFile\n\terr = json.Unmarshal(src, &stateFile)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"invalid syntax: %w\", err)\n\t}\n\tif stateFile.Backend == nil && stateFile.Remote != nil {\n\t\t// It's very unlikely to get here, but one way it could happen is\n\t\t// if this working directory was most recently used with Terraform v0.8\n\t\t// or earlier, which didn't yet include the concept of backends.\n\t\t// This error message assumes that's the case.\n\t\treturn nil, fmt.Errorf(\"this working directory uses legacy remote state and so must first be upgraded using Terraform v0.9\")","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/workdir/backend_state.go#L72-L108","documentation":"Thrown by ParseBackendStateFile when the first-pass decode succeeded but the top-level \"version\" field is 0 (missing or explicitly 0). Format version 0 corresponds to an ancient gob-binary state, never JSON, so a JSON file without a version number is treated as malformed/unsupported. Distinct from an unsupported non-zero version, which has its own error.","triggerScenarios":"Reading a backend state file that is valid JSON but lacks a \"version\" property (or has version: 0). Caused by a file not produced by Terraform, a partially-written file, or content from an unrelated tool.","commonSituations":"Hand-authored or templated backend state file missing required fields; file overwritten by a deployment script; CI artifact corruption; merge conflict resolved incorrectly leaving the version line out.","solutions":["Delete the malformed backend state file and re-run `terraform init` to recreate it.","Restore from .terraform/terraform.tfstate.backup if it has a valid version field.","Run `terraform init -reconfigure` to rebuild backend metadata from the config.","Confirm no external tooling is overwriting the backend state file."],"exampleFix":"# before: .terraform/terraform.tfstate backend metadata missing version\n# invalid syntax: no format version number\n\n# after\nrm .terraform/terraform.tfstate\nterraform init","handlingStrategy":"validation","validationCode":"// validate the backend state file has a version field before full parse\nfunc hasBackendStateVersion(raw []byte) error {\n    var probe struct{ Version int `json:\"version\"` }\n    if err := json.Unmarshal(raw, &probe); err != nil {\n        return err\n    }\n    if probe.Version == 0 {\n        return fmt.Errorf(\"missing or zero version field\")\n    }\n    return nil\n}","typeGuard":"// narrow the file to a recognised backend-state shape before using it\nfunc isBackendStateV3(raw []byte) bool {\n    var probe struct{ Version int `json:\"version\"` }\n    if json.Unmarshal(raw, &probe) != nil { return false }\n    return probe.Version == 3\n}","tryCatchPattern":null,"preventionTips":["Let Terraform own the backend state file; never template or hand-write it.","Regenerate the file with `terraform init` if the version field is missing.","Restore from backup if a version line was dropped by a bad merge.","Confirm no external tooling overwrites backend metadata."],"tags":["backend","json","version","parsing","corruption"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}