🏗️ Terraform Error: Call to unknown function for a provider-defined function

Exact Error Message

╷
│ Error: Call to unknown function
│
│   on main.tf line 12, in locals:
│   12:   arn = provider::aws::arn_build("aws", "iam", "", data.aws_caller_identity.current.account_id, "role/example")
│
│ There is no function named "provider::aws::arn_build".
╵

You may also see the more specific provider-namespace form:

│ Error: Function not found in provider
│
│ The provider "registry.terraform.io/hashicorp/aws" does not define a
│ function named "arn_build".

What It Means

Provider-defined functions (Terraform 1.8+) let a provider expose custom functions callable as provider::<local_name>::<function_name>. Unlike built-in functions such as jsonencode, these are shipped inside a provider plugin and are only available when that provider is properly declared and installed.

Call to unknown function for a provider::... reference means Terraform could not resolve the function to an installed provider. Either the provider local name in the namespace does not match a required_providers entry, the provider version installed is too old to include the function, or the function name is misspelled or does not exist in that provider.

Common Causes

• The provider is not declared in required_providers, so the provider::<name>:: namespace resolves to nothing.
• The local name used (aws, local, etc.) does not match the key you gave the provider in required_providers.
• The installed provider version predates provider-defined functions or predates that specific function.
• The function name is misspelled, or you assumed a function that the provider does not actually ship.
• Your Terraform CLI is older than 1.8 and does not support the provider:: namespace at all.

Diagnostic Commands

Check your Terraform version supports provider functions:

terraform version

Inspect declared providers and their local names/versions:

terraform providers

Show the exact installed provider versions from the lock file:

grep -A2 'provider "registry.terraform.io/hashicorp/aws"' .terraform.lock.hcl

Reproduce the resolution failure:

terraform validate

Step-by-Step Resolution

1. Confirm Terraform is 1.8 or newer. Provider-defined functions do not exist before that:

terraform version

2. Declare the provider in required_providers and note the local name (the map key). The namespace in your call must use that exact key:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.40.0"
    }
  }
}

3. Make sure the function call’s middle segment matches the local name. If you named the provider awscloud, the call must be provider::awscloud::arn_build(...), not provider::aws::....

4. Upgrade the provider so the function actually exists in the installed version, then re-lock:

terraform init -upgrade

5. Verify the function name against the provider’s documentation. For example, the AWS provider exposes arn_parse and arn_build; confirm spelling and argument order:

locals {
  parsed = provider::aws::arn_parse("arn:aws:iam::444455556666:role/example")
}

6. Run validate and plan to confirm resolution:

terraform validate && terraform plan

Success! The configuration is valid.

Prevention

• Pin a provider version constraint that is at or above the release which introduced the function you call.
• Keep the function-call namespace in sync with the required_providers local name — treat renaming a provider key as a breaking change to every provider:: call.
• Run terraform init -upgrade after adopting a new provider function so the lock file reflects a version that ships it.
• Prefer provider-defined functions over brittle string interpolation for ARNs, CIDR math, and encoding, but document the minimum provider version in a comment.
• Check the provider changelog before using a function; not every provider ships functions, and names differ between providers. The Terraform provider prompts can generate the correct required_providers block and version constraint for a function you want to use.

Related Errors

• Call to unknown function (no provider:: prefix) — a misspelled built-in function like jsondecode.
• Failed to install provider — the provider version that ships the function could not be downloaded.
• Unsupported Terraform Core version — your CLI is too old for provider:: syntax.
• Invalid provider local name — the namespace segment is not a valid identifier or is undeclared.

Frequently Asked Questions

What does the provider:: namespace mean? It is the syntax for provider-defined functions: provider::<local_name>::<function_name>. The local name must match the key you used for that provider in required_providers.

Why does Terraform say the function is unknown when the provider is installed? Usually the installed version is older than the release that added the function, or the local name in your call does not match the required_providers key. Run terraform init -upgrade and check terraform providers.

Do I need a specific Terraform version? Yes — provider-defined functions require Terraform 1.8 or newer. On older CLIs the provider:: prefix is a parse-time unknown function.

How do I know which functions a provider offers? Consult the provider’s registry documentation; function names and signatures are provider-specific and are listed under the provider’s “Functions” section. For more provider troubleshooting, see the Terraform guides.