hashicorp/terraform · error

failed to read remote state: %s

Error message

failed to read remote state: %s

What it means

Thrown in oss/client.go:433 inside getObj() after GetObject succeeded, when io.Copy from the response body stream into the in-memory buffer fails. The object was opened and metadata fetched, but the byte stream could not be fully read to completion. This is a transport-level failure on an otherwise-valid response.

Source

Thrown at internal/backend/remote-state/oss/client.go:433

	if err != nil {
		return nil, fmt.Errorf("error getting bucket %s: %#v", c.bucketName, err)
	}

	if exist, err := bucket.IsObjectExist(c.stateFile); err != nil {
		return nil, fmt.Errorf("estimating object %s is exist got an error: %#v", c.stateFile, err)
	} else if !exist {
		return nil, nil
	}

	var options []oss.Option
	output, err := bucket.GetObject(c.stateFile, options...)
	if err != nil {
		return nil, fmt.Errorf("error getting object: %#v", err)
	}

	buf := bytes.NewBuffer(nil)
	if _, err := io.Copy(buf, output); err != nil {
		return nil, fmt.Errorf("failed to read remote state: %s", err)
	}
	sum := md5.Sum(buf.Bytes())
	payload := &remote.Payload{
		Data: buf.Bytes(),
		MD5:  sum[:],
	}

	// If there was no data, then return nil
	if len(payload.Data) == 0 {
		return nil, nil
	}

	return payload, nil
}

const errBadChecksumFmt = `state data in OSS does not have the expected content.

This may be caused by unusually long delays in OSS processing a previous state

View on GitHub (pinned to c9def3e214)

Solutions

1. Retry the Terraform operation — stream-read failures are almost always transient.
2. Stabilize the network path (avoid VPN/proxy hops, run from a host in the same region as the OSS bucket).
3. Reduce state size by splitting resources into more workspaces/states to shrink the transferred payload.
4. If recurring, capture a packet/proxy log to confirm truncation and report to network/OSS support.

// Stream-read failures warrant a bounded retry on the whole Get
// for attempt := 0; attempt < 3; attempt++ {
//   payload, diags := client.Get()
//   if !diags.HasErrors() { return payload, nil }
//   time.Sleep((1 << attempt) * time.Second)
// }

When it happens

Trigger: The TCP connection is reset or dropped mid-transfer, OSS closes the response body early, a read timeout fires, or an intermediary (proxy/CDN) truncates the body. Large state files over an unstable link are the classic trigger.

Common situations: CI runner on a flaky network/VPN; very large state file transferred over a slow or metered link; corporate forward proxy buffering and then aborting; OSS internally retried and returned a partial body.

Related errors

• error getting object: %#v
• Failed to read remote state: %s
• error getting bucket: %#v
• state data in OSS does not have the expected content. This
• error getting bucket: %#v

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