How to fix Setup failed: failed unpacking terraform config: Invalid symlink has absolute target in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 142 views

This error occurs when Terraform detects a symlink with an absolute path target in your configuration or module sources during remote execution. Terraform's unpacking mechanism only allows relative symlinks to prevent security issues and portability problems.

Quick fix

Fixes Setup failed: failed unpacking terraform config: Invalid symlink has absolute target

symlink_name
pattern/to/exclude/**

Check for absolute symlinks in your configuration
Remove .terraform directory to clear cached modules
Convert absolute symlinks to relative ones
Remove problematic symlinks if they cannot be made relative

terraform — error

$symlink_name
pattern/to/exclude/**
Setup failed: failed unpacking terraform config: Invalid symlink has absolute target

What this error means

When Terraform packages your configuration for remote execution (especially in Terraform Enterprise or Cloud), it uses a 'slug' mechanism that unpacks files to a destination directory. For security and portability, symlinks within this context must have relative targets (e.g., '../module/path') rather than absolute targets (e.g., '/usr/bin/something'). Absolute symlinks can point outside the configuration directory, creating security vulnerabilities and making the package non-portable across systems.

Typical symptoms

Remote execution fails with 'Setup failed: failed unpacking terraform config'
Error message contains 'Invalid symlink has absolute target'
Local `terraform plan` works fine with -local-exec, but remote execution fails
Using terraform directories mounted in Docker or Vagrant with absolute symlinks
Module sources contain symlinks pointing to system paths

Common causes

Symlinks in your Terraform configuration directory point to absolute paths instead of relative paths
`.terraform/modules` directory contains absolute symlinks created by `terraform get` or `terraform init`
Module sources (local or remote) contain absolute symlinks that break when packaged
Mounted filesystems or development environments have absolute symlinks that don't translate to remote systems
Cached module directories with absolute symlink references being reused across different environments

How to fix "Setup failed: failed unpacking terraform config: Invalid symlink has absolute target"

1Check for absolute symlinks in your configuration

Run: find . -type l -exec sh -c 'readlink -f "$1" | grep -q "^/" && echo "Absolute: $1"' _ {} \;

This finds all symlinks with absolute targets. Note any paths returned.

2Remove .terraform directory to clear cached modules

Run: rm -rf .terraform

This removes cached modules that may contain absolute symlinks. The next init will rebuild them.

3Convert absolute symlinks to relative ones

For each absolute symlink found:

1. Note its current target: readlink symlink_name
2. Delete it: rm symlink_name
3. Recreate with relative path: ln -s ../relative/path symlink_name

For example, if a symlink at modules/common/setup.sh points to /usr/local/bin/setup.sh, recreate it as: ln -s /usr/local/bin/setup.sh modules/common/setup.sh (but make the target relative if possible).

4Remove problematic symlinks if they cannot be made relative

If a symlink points to a system path that doesn't have a relative equivalent:

1. Option A - Copy the file instead: cp /path/to/file ./local-copy
2. Option B - Reference the file differently in your code
3. Option C - Use .terraformignore to exclude the symlink:

Create .terraformignore file:

bash

symlink_name
pattern/to/exclude/**

5Verify no absolute symlinks remain

Run the check from step 1 again: find . -type l -exec sh -c 'readlink -f "$1" | grep -q "^/" && echo "Absolute: $1"' _ {} \;

The output should now be empty (no absolute symlinks found).

6Test with remote execution

If using Terraform Cloud or Enterprise:

1. Push your changes to your repository
2. Trigger a remote plan: terraform plan (with remote execution configured)
3. Verify it completes without 'unpacking' errors

For Terraform CLI with local execution, test: terraform init && terraform plan

Advanced notes

Why this matters: The go-slug library (hashicorp/go-slug) is used internally by Terraform to safely pack and unpack configuration and modules. It restricts symlinks to relative targets to ensure: (1) Security - absolute symlinks could be exploited to read arbitrary files, (2) Portability - absolute paths are system-specific and don't work across different machines or CI environments.

DereferenceSymlinks option: The go-slug library offers DereferenceSymlinks as a PackerOption, which copies symlink targets into the archive instead of storing symlinks. This is a safer alternative if you have external symlinks that must be included.

Module cache considerations: When using terraform get or terraform init, downloaded modules are cached in .terraform/modules. Clearing this directory forces Terraform to re-download and properly handle symlinks. The issue often resolves after removing and reinitializing.

Windows considerations: On Windows systems, creating true symlinks requires administrator privileges or Developer Mode. If symlink creation fails on Windows, ensure you have appropriate permissions or consider using module sources that don't rely on symlinks.

Frequently asked questions

What does "Setup failed: failed unpacking terraform config: Invalid symlink has a" mean?: When Terraform packages your configuration for remote execution (especially in Terraform Enterprise or Cloud), it uses a 'slug' mechanism that unpacks files to a destination directory. , '/usr/bin/something'). Absolute symlinks can point outside the configuration directory, creating security vulnerabilities and making the package non-portable across systems.
How do I fix "Setup failed: failed unpacking terraform config: Invalid symlink has a"?: This error occurs when Terraform detects a symlink with an absolute path target in your configuration or module sources during remote execution. Terraform's unpacking mechanism only allows relative symlinks to prevent security issues and portability problems.
What causes "Setup failed: failed unpacking terraform config: Invalid symlink has a"?: Symlinks in your Terraform configuration directory point to absolute paths instead of relative paths .terraform/modules directory contains absolute symlinks created by terraform get or terraform init Module sources (local or remote) contain absolute symlinks that break when packaged
Is the "Setup failed: failed unpacking terraform config: Invalid symlink has a" error serious?: Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.