How to fix Error: Provider alias not found in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 100 views

Terraform cannot find a referenced provider alias because it wasn't defined in your root module configuration. This error occurs when using aliased providers with modules without proper configuration passing.

Quick fix

Fixes Error: Provider alias not found

# Root module - main.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "replica"
  region = "us-west-2"
}
  1. Verify all provider aliases are defined in your root module
  2. Check module provider passing syntax
  3. Declare required provider aliases in child modules
  4. Handle orphaned resources in state
terraform — error
# Root module - main.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}
provider "aws" {
  region = "us-east-1"
}
provider "aws" {
  alias  = "replica"
  region = "us-west-2"
}
Error: Provider alias not found

What this error means

Terraform allows you to create multiple configurations for the same provider using aliases. For example, you might have AWS providers for different regions like 'aws.us-east' and 'aws.eu-west'. This error occurs when you reference an alias that either doesn't exist, wasn't passed to a module correctly, or was removed from the configuration while resources still depend on it. The error typically happens in two scenarios: (1) A module references an aliased provider that isn't defined in the root module, or (2) You removed a provider configuration from your root module while resources created by that provider still exist in your Terraform state.

Typical symptoms

  • terraform plan or terraform apply fails immediately with 'Provider alias not found'
  • Error references a specific provider alias like 'aws.replica' or 'google.secondary'
  • Error occurs when using modules with provider aliases
  • Changes to provider configuration cause validation errors
  • Downgrading or upgrading Terraform version causes the error to appear

Common causes

  1. Provider alias is referenced in a resource or module but not defined in the root module configuration
  2. Module declares that it uses an aliased provider but the parent module doesn't pass the provider explicitly
  3. Provider configuration was removed from the root module while resources still reference it in state
  4. Missing configuration_aliases declaration in child modules (Terraform 0.13+)
  5. Incorrect provider alias syntax or typo in the provider reference

How to fix "Error: Provider alias not found"

1Verify all provider aliases are defined in your root module

Check your root module (usually main.tf or providers.tf) to ensure all referenced aliases are actually defined.

Example of correct provider alias definition:

hcl
# Root module - main.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "replica"
  region = "us-west-2"
}

If you're missing a provider alias definition that your configuration needs, add it to your root module.

2Check module provider passing syntax

If you're using modules with aliased providers, ensure you're passing providers explicitly to the module.

hcl
module "app_replica" {
  source = "./modules/app"

  # Explicitly pass the aliased provider to the module
  providers = {
    aws = aws.replica
  }
}

Without the providers argument, the module receives only the default provider configuration.

3Declare required provider aliases in child modules

If you have a child module that uses aliased providers, declare them using configuration_aliases in the required_providers block.

hcl
# modules/app/main.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
      configuration_aliases = [aws.replica]
    }
  }
}

resource "aws_s3_bucket" "backup" {
  provider = aws.replica
  bucket   = "my-backup-bucket"
}

This tells Terraform and other developers that this module accepts an aliased provider.

4Handle orphaned resources in state

If you removed a provider alias from your configuration but resources still reference it in state, you have two options:

Option 1: Temporarily restore the provider to destroy resources

hcl
# Restore the provider alias
provider "aws" {
  alias  = "old_region"
  region = "deprecated-region"
}

# Resources will reference it, allowing terraform destroy

Then run:

bash
terraform destroy -target='aws_resource.name'

Option 2: Manually remove from state (advanced)

bash
terraform state rm 'aws_resource.name'

This is a last resort if you cannot restore the provider configuration.

5Validate your configuration

After making changes, validate that your configuration is correct:

bash
terraform validate

This will catch issues like:
- Undefined provider aliases
- Incorrect module provider references
- Missing configuration_aliases declarations

If terraform validate succeeds, you can proceed with terraform plan.

Advanced notes

Terraform version compatibility: Provider aliases have evolved across Terraform versions. In Terraform 0.13+, the configuration_aliases mechanism was introduced to better support modular configurations. If you're upgrading Terraform, review the changelog for provider-related changes.

Modules and for_each/count: Modules with provider configurations (instead of configuration_aliases) are incompatible with the for_each and count arguments. Always use configuration_aliases in reusable modules.

Provider source requirements: Ensure your required_providers block specifies the correct provider source and version constraints. Misconfigured sources can lead to provider resolution issues.

Frequently asked questions

What does "Error: Provider alias not found" mean?
Terraform allows you to create multiple configurations for the same provider using aliases. eu-west'. This error occurs when you reference an alias that either doesn't exist, wasn't passed to a module correctly, or was removed from the configuration while resources still depend on it.
How do I fix "Error: Provider alias not found"?
Terraform cannot find a referenced provider alias because it wasn't defined in your root module configuration. This error occurs when using aliased providers with modules without proper configuration passing.
What causes "Error: Provider alias not found"?
Provider alias is referenced in a resource or module but not defined in the root module configuration Module declares that it uses an aliased provider but the parent module doesn't pass the provider explicitly Provider configuration was removed from the root module while resources still reference it in state
Is the "Error: Provider alias not 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