What causes "Key %q could not be found" in hashicorp/terraform?

Restore the missing chunk keys from a Consul snapshot/backup.

Key %q could not be found

Error message

Key %q could not be found

What it means

In chunked mode, RemoteClient.Get (client.go:101) iterates the recorded chunk paths and reads each via kv.Get. If any chunk key returns a nil pair (deleted or never written), the state is incomplete and cannot be reconstructed, so this error is returned.

Source

Thrown at internal/backend/remote-state/consul/client.go:101

	chunked, hash, chunks, pair, err := c.chunkedMode()
	if err != nil {
		return nil, diags.Append(err)
	}
	if pair == nil {
		return nil, diags
	}

	c.modifyIndex = pair.ModifyIndex

	var payload []byte
	if chunked {
		for _, c := range chunks {
			pair, _, err := kv.Get(c, nil)
			if err != nil {
				return nil, diags.Append(err)
			}
			if pair == nil {
				return nil, diags.Append(fmt.Errorf("Key %q could not be found", c))
			}
			payload = append(payload, pair.Value[:]...)
		}
	} else {
		payload = pair.Value
	}

	// If the payload starts with 0x1f, it's gzip, not json
	if len(payload) >= 1 && payload[0] == '\x1f' {
		payload, err = uncompressState(payload)
		if err != nil {
			return nil, diags.Append(err)
		}
	}

	md5 := md5.Sum(payload)

	if hash != "" && fmt.Sprintf("%x", md5) != hash {

View on GitHub (pinned to c9def3e214)

Solutions

Restore the missing chunk keys from a Consul snapshot/backup.
Avoid manual deletion under the state path.
Ensure writes complete fully; list the Consul KV under the state path to find gaps.

Defensive patterns

Strategy: validation

Validate before calling

# verify every declared chunk key still exists in Consul
root="tfstate/<path>"
chunks="$(consul kv get "$root" | jq -r '.chunks[]?')"
for c in $chunks; do
  consul kv get "$c" >/dev/null 2>&1 || echo "MISSING chunk: $c"
done

Type guard

// verify each chunk key resolves before reconstructing state
func allChunksPresent(kv *consulapi.KV, chunks []string) bool {
    for _, c := range chunks {
        p, _, err := kv.Get(c, nil)
        if err != nil || p == nil {
            return false
        }
    }
    return true
}

Prevention

Never manually delete under the state KV path.
Back up Consul (snapshots) so chunks can be restored.
Investigate partial write failures immediately.

When it happens

Trigger: Chunked state storage where one of the chunk sub-keys (e.g. tfstate/<path>/tfstate.<hash>/<n>) was deleted or missing between the index write and the read.

Common situations: Manual KV cleanup that removed chunk keys; a partial write failure; Consul data loss/expiry; another run's cleanup deleting the wrong tree.

Related errors

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