🚨 Terraform Error Guide: 'Call to unknown function' — Fix Wrong or Missing Functions

Overview

Terraform raises this error while evaluating an expression that calls a function name it does not recognize. The name is misspelled, does not exist as a built-in, is a provider-defined function referenced without its provider:: prefix, or comes from a Terraform core version newer than the one running.

Error: Call to unknown function

  on locals.tf line 4, in locals:
   4:   names = touppercase(var.names)

There is no function named "touppercase". Did you mean "upper"?

Terraform functions are a fixed set of built-ins (plus provider-defined functions in newer versions); there is no way to define your own in HCL. So any name that is not an exact built-in — or a properly namespaced provider function — fails at evaluation time, before any resource is created.

Symptoms

• terraform validate or terraform plan fails with Call to unknown function and points at a locals, variable default, or resource argument.
• The message often includes a Did you mean "<x>"? hint for a near-miss built-in.
• A configuration that works on a colleague’s machine fails on yours, suggesting a Terraform core version gap.
• A provider-defined function like provider::aws::arn_parse(...) fails when written as arn_parse(...) without the namespace.
• Code migrated from another templating language uses functions (e.g. len, str, toupper in one form) that don’t match Terraform’s names.

Common Root Causes

• Misspelled built-in — touppercase instead of upper, lenght instead of length, jsonencodee, etc.
• Function does not exist — assuming a helper exists (map(), list() were removed; there is no reverse for maps) when Terraform has no such built-in.
• Provider-defined function without prefix — newer providers ship functions callable only as provider::<name>::<function>; omitting the prefix makes it “unknown.”
• Core version too old — the function (or provider-defined functions themselves) was added in a Terraform release newer than the one installed.
• Wrong language habits — porting Python/Bash/Jinja expressions and reaching for their function names.
• Typo in a namespaced call — misspelling the provider or function segment of a provider::... reference.

Diagnostic Workflow

Confirm the intended built-in name and swap it in. For a misspelling, the fix is usually the exact built-in:

locals {
  names = [for n in var.names : upper(n)]
}

If it is a provider-defined function, reference it with the full namespace and make sure the provider is declared:

terraform {
  required_version = ">= 1.8.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.40"
    }
  }
}

locals {
  account_id = provider::aws::arn_parse(var.role_arn).account_id
}

Check your core version against the minimum the function needs, and re-initialize so provider functions are available:

terraform version
terraform init -upgrade
terraform console

Inside terraform console, test the function on a literal to confirm it resolves before wiring it into real code:

echo 'upper("hi")' | terraform console

Example Root Cause Analysis

An engineer added account_id = arn_parse(var.role_arn).account_id and Terraform failed with Call to unknown function: There is no function named "arn_parse".

arn_parse is not a built-in; it is a provider-defined function shipped by the AWS provider. Terraform only recognizes it under its namespace, provider::aws::arn_parse. Two things were missing: the provider::aws:: prefix and a core version (>= 1.8) that supports provider-defined functions at all.

The fix was to rewrite the call as provider::aws::arn_parse(var.role_arn), set required_version = ">= 1.8.0", ensure the AWS provider version supported the function, and run terraform init -upgrade. After that the expression evaluated. The general rule: an “unknown function” that looks provider-specific almost always needs the provider:: namespace and a modern core version.

Prevention Best Practices

• Use editor tooling (terraform-ls) that autocompletes built-in and provider-defined function names so typos never reach a commit.
• Keep a required_version constraint that matches the newest function you rely on, and pin providers that supply provider-defined functions.
• Prototype expressions in terraform console before embedding them in configuration.
• Reference the official functions documentation rather than guessing from other languages; Terraform’s set is fixed and named specifically.
• Always write provider-defined functions with their full provider::<name>::<function> namespace.
• Run terraform validate in CI and pre-commit to catch unknown functions close to the author.

Quick Command Reference

terraform validate                       # catch unknown functions early
terraform version                        # confirm core version vs function needs
terraform init -upgrade                  # make provider-defined functions available
terraform console                        # interactively test an expression
echo 'upper("hi")' | terraform console   # verify a built-in resolves

Conclusion

Call to unknown function means the name in an expression is not a Terraform built-in and is not a correctly namespaced provider-defined function. Fix the spelling against the official function list, add the provider::<name>:: prefix for provider functions, and make sure your core version and providers are new enough — then verify in terraform console. Because Terraform’s function set is fixed, the resolution is always to match an existing name exactly rather than to define your own.