Problem
When executing a run in HCP Terraform or Terraform Enterprise using a self-hosted agent, the run fails with the following error message:
Operation failed: [run-id] terraform: argument list too long
This issue typically occurs during the terraform plan or terraform apply operations.
Cause
This error is not caused by Terraform itself, but by a command-line argument length limit imposed by the underlying operating system where the self-hosted agent is running.
When HCP Terraform or Terraform Enterprise initiates a run on an agent, it constructs a terraform command with various arguments, including environment variables and input variables. If the total length of this command string exceeds the OS limit (e.g., ARG_MAX on Linux-based systems), the operating system's kernel will reject the command execution, resulting in the "argument list too long" error.
This can happen if the configuration uses a very large number of variables or if the variable values themselves are extremely long.
Solutions
Here are several approaches to resolve this issue.
Solution 1: Use a Variable Definitions (.tfvars) File
Instead of passing numerous variables via the command line, you can define them in a variable definitions file and pass the file using the -var-file flag. This significantly reduces the length of the command-line arguments.
- Create a
.tfvarsfile (e.g.,production.tfvars) with your variable assignments. - In your HCP Terraform or Terraform Enterprise workspace settings, specify the path to this file in the "Terraform Working Directory" or ensure it is part of your configuration files.
For command-line driven workflows that might trigger this, use the flag directly.
$ terraform plan -var-file="production.tfvars"
Solution 2: Shorten Variable Names or Values
Review your Terraform configuration for excessively long variable names or values that contribute to the long argument string. Refactor your code to use shorter, more concise names where possible. If automation generates these variables, adjust the automation script to produce shorter outputs.
Solution 3: Adjust Operating System Limits
As a last resort, you can increase the ARG_MAX limit on the agent's host machine. This approach is highly dependent on the operating system and should be performed with caution by a system administrator, as it can have system-wide effects. Consult your operating system's documentation for instructions on how to modify kernel parameters.
Additional Information
- For more details on using variable definition files, please refer to the official Terraform documentation on Input Variables.