{"record":{"id":"e81b3232a3edf8ae","repo":"hashicorp/terraform","slug":"errnostate","errorCode":"ErrNoState","errorMessage":"no state","messagePattern":"no state","errorType":"exception","errorClass":"ErrNoState","httpStatus":null,"severity":"info","filePath":"internal/states/statefile/read.go","lineNumber":21,"sourceCode":"\npackage statefile\n\nimport (\n\t\"encoding/json\"\n\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"io/ioutil\"\n\t\"os\"\n\n\tversion \"github.com/hashicorp/go-version\"\n\n\t\"github.com/hashicorp/terraform/internal/tfdiags\"\n\ttfversion \"github.com/hashicorp/terraform/version\"\n)\n\n// ErrNoState is returned by ReadState when the state file is empty.\nvar ErrNoState = errors.New(\"no state\")\n\n// ErrUnusableState is an error wrapper to indicate that we *think* the input\n// represents state data, but can't use it for some reason (as explained in the\n// error text). Callers can check against this type with errors.As() if they\n// need to distinguish between corrupt state and more fundamental problems like\n// an empty file.\ntype ErrUnusableState struct {\n\tinner error\n}\n\nfunc errUnusable(err error) *ErrUnusableState {\n\treturn &ErrUnusableState{inner: err}\n}\nfunc (e *ErrUnusableState) Error() string {\n\treturn e.inner.Error()\n}\nfunc (e *ErrUnusableState) Unwrap() error {\n\treturn e.inner","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/states/statefile/read.go#L3-L39","documentation":"ErrNoState is a sentinel returned by statefile.Read when there is no state to read. Specifically it fires for two cases: a typed-nil *os.File was passed in, or the buffered source bytes are empty (len(src)==0). Callers are expected to detect it with errors.Is to treat 'no state yet' as a non-error (e.g. first run).","triggerScenarios":"Returned at internal/states/statefile/read.go:55 (typed-nil *os.File) and :74 (empty source). statemgr.filesystem (line 297, 475) and plans.planfile.reader wrap/compare against it; planfile wraps it in errUnusable(statefile.ErrNoState).","commonSituations":"First `terraform apply` in a fresh workspace (no terraform.tfstate yet). An empty state file touched but not written. A brand-new backend with no state object. A plan file referencing an empty tfstate. A typed-nil *os.File slipped through a code path that expected a real reader.","solutions":["If this is a fresh workspace, initialize state by running `terraform apply` (or `terraform init` for backends) — ErrNoState is expected and benign on first run.","In code that calls statefile.Read, branch on errors.Is(err, statefile.ErrNoState) and treat it as an empty/initial state rather than a hard failure.","If a state file unexpectedly became empty, restore from backend/backup (`terraform state push`) or version control.","Ensure callers do not pass a typed-nil *os.File; pass a non-nil reader (e.g. bytes.Reader) when in doubt."],"exampleFix":"// before\nf, err := statefile.Read(r)\nif err != nil {\n    return err // wrongly fatal on first run\n}\n// after\nf, err := statefile.Read(r)\nif errors.Is(err, statefile.ErrNoState) {\n    f = nil // fresh workspace, no state yet\n} else if err != nil {\n    return err\n}","handlingStrategy":"try-catch","validationCode":"// Detect empty input before reading.\nfunc isEmptyState(r io.Reader) (bool, error) {\n    b, err := io.ReadAll(r)\n    return len(b) == 0, err\n}","typeGuard":"func isNoState(err error) bool {\n    return errors.Is(err, statefile.ErrNoState)\n}","tryCatchPattern":"f, err := statefile.Read(r)\nif errors.Is(err, statefile.ErrNoState) {\n    f = nil // first run / empty backend\n} else if err != nil {\n    return err\n}","preventionTips":["Always branch on errors.Is(err, statefile.ErrNoState); never treat it as fatal.","Avoid passing typed-nil *os.File; guard with `if f, ok := r.(*os.File); ok && f == nil`.","Initialize state explicitly on fresh workspaces."],"tags":["state","statefile","initial-run","sentinel"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}