hashicorp/terraform · critical

null state found in test execution

Error message

null state found in test execution

What it means

Panics in EvalContext.getState (eval_context.go:623). It looks up a TestRunState by key in FileStates; if absent it panics, because all state keys must be initialized before the eval context is created. The comment notes this is a defensive panic to fail at the origin of the bug rather than returning nil and panicking later.

Source

Thrown at internal/moduletest/graph/eval_context.go:623

}

// GetState retrieves the current state for the specified key, exactly as it
// specified within the current cache.
func (ec *EvalContext) GetState(key string) *teststates.TestRunState {
	ec.stateLock.Lock()
	defer ec.stateLock.Unlock()
	return ec.getState(key)
}

func (ec *EvalContext) getState(key string) *teststates.TestRunState {
	current := ec.FileStates[key]
	if current == nil {
		// this shouldn't happen, all the states must be initialised prior to
		// the evaluation context being created.
		//
		// panic here, where the origin of the bug is instead of returning a
		// null state to panic later.
		panic("null state found in test execution")
	}
	return current
}

// LoadState returns the correct state for the specified run block. This differs
// from GetState in that it will load the state from any remote backend
// specified within the run block rather than simply retrieve the cached state
// (which might be empty for a run block with a backend if it hasn't executed
// yet).
func (ec *EvalContext) LoadState(run *configs.TestRun) (*states.State, error) {
	ec.stateLock.Lock()
	defer ec.stateLock.Unlock()

	current := ec.getState(run.StateKey)

	if run.Backend != nil {
		// Then we'll load the state from the backend instead of just using
		// whatever was in the state.

View on GitHub (pinned to c9def3e214)

Solutions

1. Verify every run block's state_key references an existing prior run.
2. Ensure no duplicate or missing state keys across the test file.
3. Check the .tftest.hcl structure and that the referenced run actually executes first.

Example fix

// before
run "second" { state_key = "nonexistent" }
// after
run "first"  {}
run "second" { state_key = "first" }

func stateKeyInitialized(fileStates map[string]*teststates.TestRunState, key string) error {
    if _, ok := fileStates[key]; !ok {
        return fmt.Errorf("state key %q is not initialized", key)
    }
    return nil
}

When it happens

Trigger: A module test run block references a state key that was never initialized in FileStates — typically a harness bug in moduletest state setup, or a run block whose state_key does not match any prior run.

Common situations: Terraform test files (.tftest.hcl) where a run block's state_key references a non-existent run, duplicate/missing keys, or bugs in moduletest initialization.

Related errors

• found unrecognized resource mode:
• missing field in set: %s.%s
• unknown nesting mode: %d
• error loading state: %w
• failed to write state: %w

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