“Operation failed: failed unpacking Terraform: failed creating file” error when attempting to download and unpack custom bundles via agents

Problem

When agents attempt to download and unpack custom Terraform bundles in Terraform Enterprise, the operation fails with the following error:

Operation failed: failed unpacking Terraform: failed creating file

Cause

This error occurs when the custom bundle .zip archive is created incorrectly. Specifically, the archive contains entries for directories, which the unpacking process does not handle as expected.

Solutions

There are two methods to create a valid custom bundle archive.

Solution 1: Use the Official Terraform Bundle Tool

HashiCorp provides a dedicated tool for creating custom bundles. Using this tool ensures the bundle is packaged correctly.

1. Follow the instructions to install and use the Terraform Bundle tool.
2. Generate your custom bundle using the tool's commands. This process automatically handles the correct archive structure.

Solution 2: Manually Zip with the Correct Flag

If you must create the bundle archive manually using the zip command, you need to use the -D flag. This flag prevents the command from creating entries for directories within the archive.

1. Navigate to the directory containing your custom Terraform binary.

2. Execute the zip command with the -D flag to create the archive.

   $ zip -r -D /path/to/your/bundle.zip .

Outcome

After repackaging the custom bundle using one of the solutions above, Terraform Enterprise agents will be able to download and unpack the bundle successfully, allowing Terraform runs to proceed.