Error accessing remote module registry

Problem

When running terraform init, the operation fails with the error Error accessing remote module registry. This can occur when attempting to access modules located in a Terraform Enterprise Private Module Registry.

To access these modules, the client requires an appropriate API token in the Terraform CLI Configuration File to authenticate with Terraform Enterprise.

Cause

This error typically occurs for one of the following reasons:

• The API token used for authentication is invalid or does not exist.
• The user's SAML session has expired, or the user has been removed from the organization, invalidating the token.

Solutions

Follow these solutions to diagnose and resolve the issue.

Solution 1: Verify the API Token with a Direct API Call

First, verify that the API token has the necessary permissions to access the module registry by making a direct API call to the Terraform Enterprise instance.

1. Set the required variables for your environment. The following examples show how to do this in Bash and PowerShell.

   For Bash:

   $ TOKEN="YOUR_TOKEN"
   $ HOSTNAME="YOUR_TFE_HOSTNAME"
   $ ORG_NAME="YOUR_ORGANIZATION_NAME"
   $ MODULE="YOUR_MODULE_NAME"
   $ PROVIDER="YOUR_PROVIDER_NAME"

   For PowerShell:

   $TOKEN = 'YOUR_TOKEN'
   $HOSTNAME = 'YOUR_TFE_HOSTNAME'
   $ORG_NAME = 'YOUR_ORGANIZATION_NAME'
   $MODULE = 'YOUR_MODULE_NAME'
   $PROVIDER = 'YOUR_PROVIDER_NAME'

2. Execute the API request to retrieve module versions.

   For Bash:

   $ curl \
     -H "Authorization: Bearer ${TOKEN}" \
     "https://${HOSTNAME}/api/registry/v1/modules/${ORG_NAME}/${MODULE}/${PROVIDER}/versions"

   For PowerShell:

   $params = @{
     Uri     = "https://${HOSTNAME}/api/registry/v1/modules/${ORG_NAME}/${MODULE}/${PROVIDER}/versions"
     Headers = @{ 'Authorization' = "Bearer ${TOKEN}"; 'Content-Type' = "application/vnd.api+json" }
     Method  = 'GET'
   }
   
   Invoke-RestMethod @params | ConvertTo-Json -Depth 20

3. Analyze the result.
   • If the request is successful, the API returns a JSON response listing the available module versions. This confirms the token is valid. Ensure the token in your Terraform CLI Configuration File matches the one used in this test and is configured for the correct hostname. Also, check if an Environment Variable is overriding your local configuration (supported since Terraform v1.2.0).
   • If the request fails, the token is likely invalid or has insufficient permissions. Proceed to Solution 2.

Solution 2: Address Invalid or Expired Tokens

If the API call in Solution 1 fails, the token itself is the problem. This often happens if the token is associated with a SAML user whose session has expired, causing the token to be temporarily disabled.

1. Re-authenticate the user by logging into the Terraform Enterprise UI at https://<TFE_HOSTNAME>/session.
2. If the user has been removed from the organization based on team membership mapping, re-authentication will not work. The user must be re-added to the appropriate team.
3. After ensuring the user has an active session and correct organization membership, generate a new API token.
4. Repeat the API test from Solution 1 with the new token to confirm it works.
5. Update your Terraform CLI Configuration File or environment variables with the new, valid token.