🏗️ Terraform Error: 'Error in function call' from yamldecode (invalid YAML on line N)

Exact Error Message

╷
│ Error: Error in function call
│
│   on config.tf line 5, in locals:
│    5:   settings = yamldecode(file("${path.module}/app.yaml"))
│
│ Call to function "yamldecode" failed: on line 3, column 1: did not find
│ expected key while parsing a block mapping.
╵

Other common variants of the same underlying failure:

│ Call to function "yamldecode" failed: on line 4: found character that
│ cannot start any token.

│ Call to function "yamldecode" failed: on line 2: mapping values are not
│ allowed in this context.

What It Means

yamldecode(string) parses a YAML document into a Terraform value (a map, list, or scalar). When the string is not valid YAML, the parser reports the exact line and column where it gave up. The line N in the message refers to a line inside the YAML content, not inside your .tf file.

The three example messages map to the three most common YAML mistakes: inconsistent indentation (“did not find expected key”), a literal tab character (“cannot start any token”), and an unquoted colon inside a value (“mapping values are not allowed”). Fix the YAML and the function succeeds — nothing has been provisioned yet.

Common Causes

• Tab characters used for indentation; YAML requires spaces.
• Inconsistent indentation between sibling keys in the same mapping.
• An unquoted value that contains a colon-space, e.g. url: http://x parsed as a nested key.
• A heredoc in HCL that introduced trailing whitespace or the wrong indent.
• Values like on, off, yes, no being coerced unexpectedly, or an empty file returning null.
• Windows CRLF line endings sneaking into an otherwise valid file.

Diagnostic Commands

Validate the YAML file with an external parser to get a precise pointer:

python3 -c "import yaml,sys; yaml.safe_load(open('app.yaml'))"

Reveal hidden tabs and trailing whitespace that the eye misses:

cat -A app.yaml | sed -n '1,10p'

Reproduce the decode in the Terraform console using the same input:

echo 'yamldecode(file("app.yaml"))' | terraform console

Run a validate to confirm the resource address and that this is the only parse error:

terraform validate

Step-by-Step Resolution

1. Read the line and column in the error — it points into the YAML, not your HCL. Open app.yaml and jump to that line.

2. Replace any tabs with spaces and make sibling indentation consistent. A clean mapping looks like:

service:
  name: web
  port: 8080
  replicas: 3

3. Quote values that contain colons, #, or leading special characters so they are not parsed as structure:

endpoints:
  api: "http://internal:8080/health"
  note: "ratio 1:1, keep quoted"

4. If the YAML is inline via a heredoc, use the indent-stripping form <<-EOT and keep the body left-aligned so no stray indentation leaks in:

locals {
  raw = <<-EOT
    service:
      name: web
      port: 8080
  EOT
  settings = yamldecode(local.raw)
}

5. Guard against an empty file returning null before you index into the result:

locals {
  cfg = yamldecode(file("${path.module}/app.yaml"))
  # coalesce so downstream lookups don't hit null
  port = try(local.cfg.service.port, 8080)
}

6. Re-test in the console, then validate:

echo 'yamldecode(file("app.yaml"))' | terraform console
terraform validate

Prevention

• Lint YAML in CI with yamllint or a python -c "import yaml" check before Terraform ever runs.
• Configure your editor to show whitespace and to insert spaces, never tabs, in .yaml files.
• Quote any scalar containing :, #, {, }, or a leading !/&/*.
• Prefer <<-EOT heredocs for inline YAML so indentation is normalized.
• Wrap decoded lookups in try() so an empty or partial file degrades gracefully instead of crashing the plan.

Related Errors

• Error in function call from jsondecode — the JSON equivalent of this parse failure.
• Invalid template interpolation value — interpolating a decoded map/list into a string context.
• Unsupported attribute — reading a key from the decoded map that the YAML did not actually define.
• Call to function "file" failed — the file path is wrong, so yamldecode never receives content.

Frequently Asked Questions

Which file does “line 3” refer to? The line number is inside the YAML content passed to yamldecode, not your .tf file. Open the YAML source and go to that line and column.

Why does my URL break the parse? An unquoted value with a colon-space, like url: http://x, is read as a nested mapping. Wrap the value in quotes: url: "http://x".

Can a valid file still return null? Yes — an empty document decodes to null. Use try() or coalesce() before indexing so a blank file does not fault later expressions. A Terraform prompt can help you write the guard cleanly.

Are tabs really the problem? Very often. YAML forbids tabs for indentation; run cat -A to spot them, then replace with spaces. For more decoding and template fixes, see the Terraform guides.