🚨 OpenTofu Error: 'Invalid function argument' — Cause, Fix, and Troubleshooting Guide

Overview

OpenTofu’s built-in functions validate their arguments. When you pass a value of the wrong type, a null, or malformed content — for example non-JSON to jsondecode or a list where a map is expected — the function fails and OpenTofu reports which argument was invalid:

Error: Invalid function argument

  on main.tf line 18, in locals:
  18:   config = jsondecode(var.raw_config)

Invalid value for "str" parameter: a JSON document is required; got a string
that is not valid JSON: invalid character 'k' looking for beginning of object
key string.

Symptoms

• tofu plan/validate fails with Invalid function argument.
• The detail names the parameter and why it is invalid (wrong type, not valid JSON, out of range).
• Common with jsondecode, cidrsubnet, element, lookup, file, templatefile, and format.
• Often triggered by an unexpected variable value at plan time.

Common Root Causes

• Wrong type — passing a string where a list/number is required, or vice versa.
• Malformed content — invalid JSON/YAML/HCL fed to jsondecode/yamldecode.
• Null value — a variable resolved to null and reached a function that rejects it.
• Out-of-range index — element/substr beyond the collection length.
• Bad CIDR / format string — cidrsubnet with too many new bits, or format verb/type mismatch.

How to diagnose

Read the parameter name and reason in the detail, then inspect the input:

tofu plan 2>&1 | sed -n '1,20p'

Evaluate the expression interactively with real values:

echo 'jsondecode(file("config.json"))' | tofu console

Validate the raw content the function receives:

jq . config.json          # is it valid JSON?
tofu console <<< 'var.subnet_bits'

Fixes

Coerce or fix the type before passing it in:

locals {
  ports = [for p in split(",", var.ports_csv) : tonumber(p)]
}

Guard against null/empty so the function never sees an invalid value:

locals {
  config = var.raw_config != null && var.raw_config != "" ? jsondecode(var.raw_config) : {}
}

Fix out-of-range CIDR math by keeping new bits within the prefix budget:

# a /16 base with 8 new bits => /24 subnets (valid)
cidr = cidrsubnet("10.0.0.0/16", 8, count.index)

Validate inputs with a variable validation block so bad values fail early with a clear message.

What to watch out for

• tofu console is the fastest way to test a function against real inputs without an apply.
• Decode functions need well-formed content — validate JSON/YAML at the source, not in HCL.
• Add validation blocks to variables so callers get a targeted error instead of a deep function failure.
• null propagates silently; guard optional inputs before functions that reject it.

Related

• OpenTofu Error: ‘Unsuitable value type’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Invalid count argument’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Missing required argument’ — Cause, Fix, and Troubleshooting Guide