hashicorp/terraform · error

Failed to %s: %v

Error message

Failed to %s: %v

What it means

c.Client.Do(req) failed — the request was built but the actual HTTP round-trip errored. retryablehttp will already have retried up to retry_max times with backoff between retry_wait_min and retry_wait_max, so this surfaces only after all retries are exhausted. Causes include DNS resolution failure, connection refused/timeout, TLS handshake errors, or a broken pipe mid-stream.

Source

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

	if c.Username != "" {
		req.SetBasicAuth(c.Username, c.Password)
	}

	// Work with data/body
	if data != nil {
		req.Header.Set("Content-Type", "application/json")
		req.ContentLength = int64(len(*data))

		// Generate the MD5
		hash := md5.Sum(*data)
		b64 := base64.StdEncoding.EncodeToString(hash[:])
		req.Header.Set("Content-MD5", b64)
	}

	// Make the request
	resp, err := c.Client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("Failed to %s: %v", what, err)
	}

	return resp, nil
}

func (c *httpClient) Lock(info *statemgr.LockInfo) (string, error) {
	if c.LockURL == nil {
		return "", nil
	}
	c.lockID = ""

	jsonLockInfo := info.Marshal()
	resp, err := c.httpRequest(c.LockMethod, c.LockURL, &jsonLockInfo, "lock")
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

View on GitHub (pinned to c9def3e214)

Solutions

1. Check connectivity: `curl -v <address>` from the same host/CI runner where terraform runs.
2. Verify DNS resolves: `getent hosts <hostname>` or `dig +short <hostname>`.
3. If TLS validation fails, either install the CA via client_ca_certificate_pem or, only for trusted internal CAs, set skip_cert_verification = true (avoid in production).
4. Raise retry_max and retry_wait_max to better tolerate transient outages.
5. Confirm HTTP_PROXY/HTTPS_PROXY/NO_PROXY are set correctly for your network.

Example fix

// before
backend "http" {
  address       = "https://state.corp/state"
  retry_max     = 0
}
// after
backend "http" {
  address        = "https://state.corp/state"
  retry_max      = 4
  retry_wait_min = 1
  retry_wait_max = 30
}

// Pre-flight connectivity check before terraform runs
import (
  "fmt"
  "net"
  "net/url"
  "time"
)
func preflightReachable(raw string) error {
  u, err := url.Parse(raw)
  if err != nil { return err }
  host := u.Hostname()
  if _, ok := u.Port(""); ok { host = net.JoinHostPort(host, u.Port()) }
  c, err := net.DialTimeout("tcp", host, 5*time.Second)
  if err != nil { return fmt.Errorf("cannot reach state host: %w", err) }
  c.Close()
  return nil
}

// Wrap state ops with bounded retry; distinguish transport errors from business errors.
for attempt := 0; attempt < maxAttempts; attempt++ {
  err = runTerraform()
  if err == nil { break }
  if isTransportErr(err) && attempt < maxAttempts-1 {
    backoff.Sleep(); continue
  }
  return err
}

When it happens

Trigger: State endpoint host is unreachable, DNS NXDOMAIN, TCP connection refused (server down), TLS certificate validation failure when skip_cert_verification is false, proxy misconfiguration, or network partition. Fires on Get/Put/Delete/Lock/Unlock.

Common situations: VPN not connected when running terraform locally; state server behind a private IP not reachable from CI; cert expired or signed by an unknown CA; corporate proxy environment variables not honored; transient outage during a long apply.

Related errors

• HTTP remote state already locked, failed to read body
• operation timed out
• operation timed out
• retrieving %s: %+v
• failed to parse unlock_address URL: %s

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