GitHub Actions hashicorp/setup-terraform wrapper conflict

hashicorp/setup-terraform installs a wrapper script in front of terraform so it can expose stdout, stderr, and exitcode as step outputs. Calling terraform from another path, or running two setup steps, makes the wrapper and the real binary disagree.

What this error means

Terraform step outputs (stdout/exitcode) are empty, or a later terraform call behaves differently than the wrapped one, after setup-terraform ran.

Error: The process '/usr/local/bin/terraform' failed because one or more lines
were written to the STDERR stream
(terraform_wrapper expected JSON but the real binary was invoked)

Common causes

Real binary called instead of the wrapper

A hardcoded path or a tool that re-resolves terraform bypasses the wrapper, so the documented step outputs are never populated.

Wrapper disabled but outputs still consumed

Setting terraform_wrapper: false removes the outputs that a later step references.

How to fix it

Align wrapper usage with how you call terraform

1. Keep terraform_wrapper enabled (default) if you read stdout/exitcode outputs.
2. Call terraform via PATH so the wrapper is used, not an absolute path.
3. If you need the raw binary, set terraform_wrapper: false and stop reading wrapper outputs.

- uses: hashicorp/setup-terraform@v3
  with:
    terraform_wrapper: true

How to prevent it

• Decide once whether you want the wrapper, and keep all terraform calls consistent.
• Reference terraform through PATH inside the same job that ran setup-terraform.

Related guides