hashicorp/terraform · error

failed to read remote state

Error message

failed to read remote state: %s

What it means

Thrown by RemoteClient.getObj when io.Copy from the OSS GetObject response body into an in-memory buffer fails. The object was opened successfully; the failure is a streaming read error mid-download. The %s formats the underlying error (usually a network or connection reset).

Solutions

1. Retry the apply/init - streaming errors are typically transient.
2. Reduce state size by splitting resources or using workspaces to shrink each state file.
3. Run from a host in the same region as the OSS bucket (lower latency, fewer resets).
4. Disable or reconfigure any HTTP proxy that truncates long responses.

// set a per-read budget sized for the state file
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
// pass ctx to the SDK call so streaming reads respect the deadline

for attempt := 0; attempt < 3; attempt++ {
    output, err := bucket.GetObject(c.stateFile)
    if err != nil { return err }
    buf := bytes.NewBuffer(nil)
    if _, err := io.Copy(buf, output); err == nil { break } else { lastErr = err }
}

When it happens

Trigger: io.Copy(buf, output) returns err != nil while streaming the object body. Causes: connection reset by OSS, premature close, client timeout mid-download, large state file exceeding a proxy buffer, or a reader that returned EOF incorrectly.

Common situations: Flaky network to OSS region; large state files (tens of MB) over a constrained CI network; corporate proxy terminating long reads; transient OSS-side connection drop.

Related errors

• estimating object is exist got an error: %#v
• describe oss endpoint using region: %#v got an error: %#v
• error getting object: %#v
• failed to read existing lock file content
• failed to read the body of the S3 object

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

Appendix: 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 d32a084675)