How to fix Error: Required token could not be found in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 151 views

This error occurs when Terraform cannot locate authentication credentials for Terraform Cloud (app.terraform.io). The token must be configured in your CLI config file, environment variables, or interactive login to access remote backends and registries.

Quick fix

Fixes Error: Required token could not be found

terraform login
  1. Generate a new API token in Terraform Cloud
  2. Configure credentials using terraform login
  3. Manually create credentials.tfrc.json (if terraform login doesn't work)
  4. For CI/CD pipelines, use environment variables
terraform — error
terraform login
Error: Required token could not be found

What this error means

Terraform Cloud requires authentication for remote state storage, module registries, and policy enforcement. When Terraform tries to connect to app.terraform.io or other Terraform Cloud services, it looks for an API token in three places: your .terraform.d/credentials.tfrc.json file, the TFE_TOKEN environment variable, or interactive login. If none of these sources provide a valid token, Terraform fails with this error. The error message is often cryptic because it doesn't indicate which authentication method failed or why—you must check all three sources to identify the root cause.

Typical symptoms

  • terraform init, plan, or apply fails immediately with "Error: Required token could not be found"
  • Error message suggests configuring credentials in CLI Config File for app.terraform.io
  • terraform login command doesn't help or isn't interactive in CI/CD environments
  • Remote backend initialization fails even though you have a valid Terraform Cloud account
  • Cloud modules or policy enforcement is unavailable due to authentication failure

Common causes

  1. Credentials file missing or in wrong location (~/.terraform.d/credentials.tfrc.json expected)
  2. Token not created or expired in Terraform Cloud UI
  3. TFE_TOKEN or TF_TOKEN_app_terraform_io environment variable not set or incorrect
  4. Snap installation of Terraform looking for credentials in snap home directory instead of user home
  5. Credentials file has incorrect JSON format or missing token entry for app.terraform.io
  6. GitHub Actions or CI/CD environment not providing token through environment variables
  7. Wrong token type used (organization token vs user token in cloud-based workflows)

How to fix "Error: Required token could not be found"

1Generate a new API token in Terraform Cloud

Visit Terraform Cloud (https://app.terraform.io), sign in, and create a new API token:

1. Click your profile icon (top right) → Account settings
2. Navigate to "Tokens"
3. Click "Create an API token"
4. Give it a descriptive name (e.g., "Local dev" or "CI/CD")
5. Choose appropriate scope (usually "Full access")
6. Click "Generate token"
7. Copy the token immediately — it is only displayed once

Save the token to a text editor temporarily. Do not lose it; you'll need it in the next steps.

2Configure credentials using terraform login

The simplest method for local development is the terraform login command:

bash
terraform login

Terraform will:
1. Prompt: "Do you want to copy these credentials to the local credentials file? (yes/no)"
2. Open a browser to app.terraform.io to create a token (if not already done)
3. Ask you to paste the token back into the terminal
4. Automatically save credentials to ~/.terraform.d/credentials.tfrc.json

After this, terraform init and other commands should work. Verify:

bash
terraform init
3Manually create credentials.tfrc.json (if terraform login doesn't work)

If terraform login is unavailable or non-interactive (common in CI/CD), manually create the credentials file:

bash
mkdir -p ~/.terraform.d

Create ~/.terraform.d/credentials.tfrc.json:

json
{
  "credentials": {
    "app.terraform.io": {
      "token": "YOUR_API_TOKEN_HERE"
    }
  }
}

Replace YOUR_API_TOKEN_HERE with your actual Terraform Cloud API token (from step 1).

Set proper permissions:

bash
chmod 600 ~/.terraform.d/credentials.tfrc.json

Verify the file was created and is readable:

bash
ls -la ~/.terraform.d/credentials.tfrc.json
4For CI/CD pipelines, use environment variables

In automated environments (GitHub Actions, GitLab CI, Jenkins), use the TF_TOKEN_app_terraform_io environment variable instead of file-based credentials:

GitHub Actions example:

yaml
jobs:
  terraform:
    runs-on: ubuntu-latest
    env:
      TF_TOKEN_app_terraform_io: ${{ secrets.TERRAFORM_API_TOKEN }}
    steps:
      - uses: actions/checkout@v3
      - uses: hashicorp/setup-terraform@v2
      - run: terraform init
      - run: terraform plan

GitLab CI example:

yaml
terraform-plan:
  image: hashicorp/terraform:latest
  variables:
    TF_TOKEN_app_terraform_io: $TERRAFORM_API_TOKEN
  script:
    - terraform init
    - terraform plan

The TF_TOKEN_ prefix combined with hostname (app.terraform.io becomes app_terraform_io) tells Terraform where to use this token. Store the actual token value in your CI/CD platform's secrets management, not in code.

5For Snap installations, create a symlink to fix path issues

If you installed Terraform via snap, it may look for credentials in the wrong location:

bash
mkdir -p ~/.terraform.d
ln -s ~/.terraformrc ~/.terraform.d/credentials.tfrc.json

If you haven't created ~/.terraformrc yet, first generate it with terraform login, then create the symlink above. Verify the symlink:

bash
ls -la ~/.terraform.d/

You should see:

bash
lrwxrwxrwx credentials.tfrc.json -> ~/.terraformrc

Test that Terraform can now authenticate:

bash
terraform version  # Should not error if credentials are valid
6For remote backends on custom hosts, add credentials for that host

If using a self-hosted Terraform Enterprise or custom backend server (not app.terraform.io), add credentials for that hostname:

json
{
  "credentials": {
    "app.terraform.io": {
      "token": "YOUR_CLOUD_TOKEN"
    },
    "terraform.example.com": {
      "token": "YOUR_ENTERPRISE_TOKEN"
    }
  }
}

Or via environment variable (replace hostname with underscores):

bash
export TF_TOKEN_terraform_example_com="YOUR_ENTERPRISE_TOKEN"

Then configure your backend block:

hcl
terraform {
  cloud {
    hostname = "terraform.example.com"
    organization = "my-org"
  }
}

Verify connectivity:

bash
terraform init

Advanced notes

Terraform token management has evolved. Older documentation mentions TFE_TOKEN, but the recommended modern pattern is TF_TOKEN_{hostname} where the hostname replaces dots with underscores. Both work, but TF_TOKEN_* is more explicit and supports multiple backends.

Token scope and permissions: User tokens have "Full access" by default. Organization tokens and team tokens have more restricted scopes. If you're seeing "insufficient permissions" errors after fixing the "token not found" error, you may need a user token rather than an organization token.

Snap and containerized Terraform: Snap sandboxing and container isolation can cause credential file visibility issues. If running terraform in Docker, mount ~/.terraform.d as a volume or pass credentials via environment variables. For snap, the snap confinement model may prevent access to your home directory entirely—consider installing via apt or Homebrew instead.

Terraform Cloud organization management: If you have multiple Terraform Cloud organizations, each with different tokens, you'll need separate credentials entries for each, or use organization-specific environment variables at the CI/CD level. Team workflows often require a dedicated service account token rather than personal user tokens.

Frequently asked questions

What does "Error: Required token could not be found" mean?
Terraform Cloud requires authentication for remote state storage, module registries, and policy enforcement. json file, the TFE_TOKEN environment variable, or interactive login. If none of these sources provide a valid token, Terraform fails with this error.
How do I fix "Error: Required token could not be found"?
This error occurs when Terraform cannot locate authentication credentials for Terraform Cloud (app.terraform.io). The token must be configured in your CLI config file, environment variables, or interactive login to access remote backends and registries.
What causes "Error: Required token could not be found"?
Credentials file missing or in wrong location (~/.terraform.d/credentials.tfrc.json expected) Token not created or expired in Terraform Cloud UI TFE_TOKEN or TF_TOKEN_app_terraform_io environment variable not set or incorrect
Is the "Error: Required token could not be found" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading