Introduction
Terraform Agents allow HCP Terraform and Terraform Enterprise to communicate with isolated, private, or on-premises infrastructure. Agents also support running custom programs called hooks to extend their functionality.
Problem
When a custom agent hook script executes the terraform init command to download public modules, the operation fails with the following error:
Error: Failed to download module
With TRACE log level enabled for the agent, the logs show a more specific error message indicating that Git is not available in the execution environment's PATH.
git must be available and on the PATH
This error can occur even if Git is installed on the agent host and terraform init runs successfully when executed manually via SSH.
Prerequisites
- HCP Terraform or Terraform Enterprise
- A configured Terraform agent using hooks
Cause
The custom hook script runs in an environment that does not inherit the host's full PATH environment variable. As a result, the script cannot locate the git executable, which is required by Terraform to download modules from Git-based sources.
Solutions
Solution 1: Add the Git Executable to the Agent's PATH
To resolve this issue, you must explicitly add the directory containing the git executable to the PATH environment variable within your hook script.
- Connect to the host machine or Docker container where the Terraform agent is running.
-
Locate the absolute path to the
gitexecutable.$ which git
The command returns the path to the executable.
/usr/bin/git
-
Modify your custom hook script to export the updated
PATH, including the directory from the previous step. In this example, the directory is/usr/bin.#!/bin/bash export PATH=$PATH:/usr/bin terraform init
- Restart the Terraform agent to apply the changes to the hook script.
Outcome
After restarting the agent, the custom hook script will execute terraform init successfully, and Terraform will be able to download the required modules without errors.