Terraform Cloud "Required token could not be found" in CI

By Daniel Zoghalchali·Latchkey

The cloud {} block needs an API token to reach HCP Terraform, and the runner has none. terraform login was never run and neither TF_TOKEN_app_terraform_io nor a credentials file is present, so init aborts before contacting the backend.

What this error means

terraform init fails immediately with "Error: Required token could not be found" and a hint to run terraform login or set the token variable. It happens on fresh CI runners that carry no credentials file.

Error: Required token could not be found

Run the following command to generate a token for app.terraform.io:
    terraform login

Common causes

No credentials on an ephemeral runner

CI runners start clean and never ran terraform login, so there is no ~/.terraform.d/credentials.tfrc.json for the CLI to read.

The token env var name is wrong

The host-specific var must be TF_TOKEN_app_terraform_io (dots in the hostname become underscores). A misnamed secret is ignored and the CLI falls back to nothing.

How to fix it

Set the host token variable from a secret

1. Create an API token (user, team, or organization) in HCP Terraform.
2. Store it as a CI secret and expose it as TF_TOKEN_app_terraform_io.
3. Confirm the env var name maps app.terraform.io exactly with underscores.

env:
  TF_TOKEN_app_terraform_io: ${{ secrets.TF_API_TOKEN }}

Or write a credentials file

If you prefer a credentials block, write the tfrc file before init so the CLI can read it.

mkdir -p ~/.terraform.d
cat > ~/.terraform.d/credentials.tfrc.json <<EOF
{ "credentials": { "app.terraform.io": { "token": "${TF_API_TOKEN}" } } }
EOF

How to prevent it

• Inject TF_TOKEN_app_terraform_io in CI, never commit a token.
• Use a team or organization token scoped to the workspaces CI touches.
• Match the env var to the hostname exactly (dots to underscores).

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation