🏗️ Terraform Error: 'reference to undeclared provider' Aliased Provider Not Configured

Exact Error Message

╷
│ Error: reference to undeclared provider
│
│   on main.tf line 24, in resource "aws_s3_bucket" "replica":
│   24:   provider = aws.us_west
│
│ There is no provider "aws" with alias "us_west".
│
│ To reference a provider configuration, you must first declare it in a
│ required_providers block and a provider block with a matching alias.
╵

You may also see the module-facing variant Provider configuration not present or provider aws.us_west is undefined when a child module expects an aliased provider that the root never passed in.

What It Means

Terraform lets you configure the same provider more than once by giving each extra configuration an alias. A resource, data source, or module then opts into a specific configuration with provider = aws.us_west. This error means you referenced an alias that was never declared. Terraform validated the reference before planning and could not find a provider "aws" block whose alias matches, so it stops.

The most common trigger is multi-region or multi-account AWS setups where a second provider block was forgotten, misspelled, or defined inside a module that cannot see it. The default (unaliased) provider is separate from every aliased one, so having a plain provider "aws" {} block does not satisfy a reference to aws.us_west.

Common Causes

• The aliased provider block was never written, only referenced on a resource.
• A typo: the resource says aws.us_west but the block declares alias = "uswest".
• A child module uses provider = aws.us_west without a configuration_aliases entry in its required_providers.
• The root module forgot the providers = { ... } map when calling a module that needs an aliased provider.
• The alias lives in a different module scope; aliases do not inherit automatically into child modules.

Diagnostic Commands

Validate the configuration to surface every undeclared reference at once:

terraform validate

List which providers Terraform thinks the configuration requires:

terraform providers

Search the codebase for the alias to see where it is declared versus referenced:

grep -rn "aws.us_west\|alias" *.tf modules/

Run an init and plan to confirm the reference resolves after fixing:

terraform init
terraform plan

Step-by-Step Resolution

1. Declare the aliased provider in the root module. Every alias needs its own provider block:

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

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

2. Reference it exactly, matching the alias string character-for-character:

resource "aws_s3_bucket" "replica" {
  provider = aws.us_west
  bucket   = "example-replica-bucket"
}

3. If the reference is inside a child module, declare the alias with configuration_aliases so the module knows it expects to be handed that provider:

# modules/replication/versions.tf
terraform {
  required_providers {
    aws = {
      source                = "hashicorp/aws"
      configuration_aliases = [aws.us_west]
    }
  }
}

4. Pass the configured provider from the root when calling that module. Without the providers map, the child sees no aliased provider:

module "replication" {
  source = "./modules/replication"
  providers = {
    aws.us_west = aws.us_west
  }
}

5. Re-initialize so Terraform records the provider requirements, then validate:

terraform init
terraform validate

Success! The configuration is valid.

6. Plan to confirm the resource now binds to the correct region/account.

Prevention

• Keep all provider blocks (default and aliased) in one providers.tf file so missing aliases are obvious.
• Always add configuration_aliases in a module’s required_providers for any provider the module references by alias.
• Pass providers explicitly with the providers = {} map when a module needs a non-default configuration; do not rely on implicit inheritance.
• Standardize alias names (for example aws.us_east_1, aws.us_west_2) across the repo to avoid typos.
• Run terraform validate in CI on every change to catch undeclared references before apply.

Related Errors

• Reference to undeclared input variable — a missing variable block, the input-variable analogue of this error.
• Provider configuration not present — a passed-through provider was removed from a module’s inputs but is still referenced.
• Duplicate provider configuration — two provider blocks share the same alias (or both omit one).
• Invalid provider configuration — the provider block exists but a required argument is missing or malformed.

Frequently Asked Questions

Why does my default provider "aws" block not satisfy aws.us_west? The default (unaliased) provider and every aliased provider are distinct configurations. A resource referencing aws.us_west needs a provider "aws" block with alias = "us_west" specifically.

Do child modules inherit aliased providers automatically? No. Only the default provider is inherited implicitly. Aliased providers must be declared with configuration_aliases and passed in via the providers = {} map on the module call.

How do I fix this in a reusable module? Add the alias to the module’s required_providers using configuration_aliases = [aws.us_west], then have every caller pass the provider explicitly. For prompts that scaffold multi-provider modules, see the Terraform prompt library.

Can a typo really cause this? Yes. The alias is matched by exact string, so us_west versus uswest will fail. Run terraform providers and grep for the alias to compare declaration and reference.

Where do I go for more Terraform provider fixes? See the full Terraform guides for related init, provider, and module troubleshooting.