Terraform Cloud "context deadline exceeded" in CI

A call to the HCP Terraform API did not complete within its timeout. "context deadline exceeded" is a client-side timeout: the request was slow or the endpoint was unreachable, usually a network or proxy issue rather than a bad config.

What this error means

terraform init, plan, or a state operation fails with "Error: context deadline exceeded" or "Client.Timeout exceeded while awaiting headers" against app.terraform.io.

terraform

Error: context deadline exceeded (Client.Timeout exceeded while awaiting headers)

  while requesting https://app.terraform.io/api/v2/...

Common causes

Transient slowness or an unreachable API

Momentary latency, packet loss, or a brief HCP Terraform slowdown makes a request exceed its deadline.

A proxy or firewall dropping the connection

A restrictive egress proxy that does not allow or slowly handles app.terraform.io causes the client to time out.

How to fix it

Retry the operation

Treat the timeout as transient and re-run the step.
Confirm the runner can reach app.terraform.io promptly.
If it recurs, inspect proxy latency to the API.

Fix egress to the API

Allow HTTPS to app.terraform.io through any proxy or firewall and ensure DNS resolves quickly on the runner.

Terminal

curl -s -o /dev/null -w "%{http_code}\n" https://app.terraform.io/.well-known/terraform.json

How to prevent it

Allow fast egress to app.terraform.io from CI runners.
Retry transient timeouts rather than failing the whole job.
Keep runner DNS and proxy configuration healthy.