hashicorp/terraform · error

Failed to read remote state

Error message

Failed to read remote state: %s

What it means

Thrown when io.Copy from resp.Body into a buffer fails while reading the state payload (client.go:171-175). The %s is the underlying I/O error. This occurs after a successful status code (200 OK) but during body streaming, so the connection broke mid-transfer.

Solutions

1. Retry the Terraform command — transient I/O failures often clear on the next attempt.
2. If recurring, check for proxy/intermediary read timeouts that are shorter than large-state transfer time.
3. Reduce state size (split resources into workspaces) if transfers consistently time out.
4. Verify network stability to the state endpoint (latency, packet loss).

// Retry body-read failures with backoff; they are typically transient:
// var payload *remote.Payload
// for attempt := 0; attempt < maxAttempts; attempt++ {
//   var diags tfdiags.Diagnostics
//   payload, diags = httpClient.Get()
//   if !diagsHas(diags, "Failed to read remote state") { break }
//   time.Sleep(backoff(attempt))
// }

When it happens

Trigger: The TCP connection is reset or dropped while the response body is being read; a proxy closes the connection after a timeout; the server streams slowly and an intermediary cuts it off; TLS handshake succeeds but the socket dies during transfer.

Common situations: Flaky network or VPN dropping long-lived connections; a reverse proxy with an aggressive read timeout; large state files exceeding a proxy body-size/time limit mid-stream; cloud network blips.

Related errors

• bucket not exists
• failed checking for existing remote state
• failed to create bucket
• failed to delete bucket
• failed to delete file

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

Appendix: source

Thrown at internal/backend/remote-state/http/client.go:174

		// Handled after
	case http.StatusNoContent:
		return nil, diags
	case http.StatusNotFound:
		return nil, diags
	case http.StatusUnauthorized:
		return nil, diags.Append(fmt.Errorf("HTTP remote state endpoint requires auth"))
	case http.StatusForbidden:
		return nil, diags.Append(fmt.Errorf("HTTP remote state endpoint invalid auth"))
	case http.StatusInternalServerError:
		return nil, diags.Append(fmt.Errorf("HTTP remote state internal server error"))
	default:
		return nil, diags.Append(fmt.Errorf("Unexpected HTTP response code %d", resp.StatusCode))
	}

	// Read in the body
	buf := bytes.NewBuffer(nil)
	if _, err := io.Copy(buf, resp.Body); err != nil {
		return nil, diags.Append(fmt.Errorf("Failed to read remote state: %s", err))
	}

	// Create the payload
	payload := &remote.Payload{
		Data: buf.Bytes(),
	}

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

	// Check for the MD5
	if raw := resp.Header.Get("Content-MD5"); raw != "" {
		md5, err := base64.StdEncoding.DecodeString(raw)
		if err != nil {
			return nil, diags.Append(fmt.Errorf(
				"Failed to decode Content-MD5 '%s': %s", raw, err))

View on GitHub (pinned to d32a084675)