Discovery document ERROR: .well-known/terraform.json

Introduction

This document addresses the intermittent Error: Failed to create client: failed to request discovery document: Get "https://app.terraform.io/.well-known/terraform.json": context deadline exceeded observed during Terraform runs. This error indicates that the client (your Terraform run) failed to receive a response from the Terraform Cloud registry within the default timeout period.

Expected Outcome

Users should be able to complete their Terraform remote runs without encountering the Client.Timeout exceeded while awaiting headers error caused by the default discovery timeout.

Use Case

A Terraform remote run fails intermittently with a timeout error when attempting to fetch the necessary discovery document

Procedure

Workaround to extend discovery timeout

• Navigate to the affected Workspace in your HCP Terraform Cloud application.
• Go to the Variables section of the workspace settings.
• Click Add variable and configure the following settings:
  • Key: TF_REGISTRY_CLIENT_TIMEOUT
  • Value: Set to a higher value than the default (e.g., 90s, 120s, or 3m). This value is the maximum time the client should wait for the discovery request.
  • Category: Select Environment Variable.
• Click Save variable.
• The next remote run will utilize this extended timeout, reducing the likelihood of the connection error due to server saturation.

Additional Information

• Root Cause: The underlying cause is suspected to be Puma saturation on the server, causing request queuing and eventual timeout of the client's default discovery request.
• Engineering Mitigation: The internal engineering team is aware of the Puma saturation issue and is actively working on long-term mitigations to resolve it downstream.