🚨 OpenTofu Error: 'Unsuitable value type' — Cause, Fix, and Troubleshooting Guide

Overview

OpenTofu enforces the declared type of variables, outputs, and arguments. When a supplied value cannot convert to the expected type — a string where a number is needed, a list where a map is required, or a null where a value is mandatory — it reports an unsuitable value type:

Error: Unsuitable value type

  on variables.tf line 3, in variable "instance_count":
   3:   type = number

Unsuitable value: a number is required, but the given value is a string
"three" that cannot be converted to number.

Symptoms

• tofu plan/validate fails with Unsuitable value type (or “Invalid value for input variable”).
• The message names the expected type and the value that could not convert.
• Common with .tfvars, TF_VAR_* env vars, and module inputs.
• Also appears when an object/map is missing required attributes for a typed variable.

Common Root Causes

• String vs number/bool — env vars are strings; TF_VAR_count=3 may not convert as expected in complex types.
• Wrong collection type — passing a list where a map/set is declared, or vice versa.
• Object attribute mismatch — a typed object variable missing keys or with wrong-typed keys.
• null for a non-nullable type without a default.
• Malformed .tfvars value (quotes, brackets) producing the wrong type.

How to diagnose

Read the expected type and offending value, then check the declaration:

tofu plan 2>&1 | sed -n '1,15p'
grep -nA4 'variable "instance_count"' variables.tf

Inspect how the value is being supplied:

grep -rn 'instance_count' *.tfvars
env | grep TF_VAR_

Test conversion in the console:

echo 'tonumber("three")' | tofu console

Fixes

Provide the correctly typed value:

# terraform.tfvars
instance_count = 3          # number, not "3" as a bare string type mismatch

Convert explicitly when the source is unavoidably a string (env vars):

locals {
  count = tonumber(var.instance_count_str)
}

Match the declared collection type — use a map when a map is expected:

variable "tags" { type = map(string) }

# tfvars
tags = { Environment = "prod", Team = "platform" }

Complete typed object variables with all required attributes:

variable "db" {
  type = object({ engine = string, size = number })
}
# tfvars
db = { engine = "postgres", size = 20 }

What to watch out for

• All TF_VAR_* environment values arrive as strings; declare type accordingly or convert with tonumber/tobool.
• Use optional() in object type constraints for attributes that may be omitted, with defaults.
• tofu console quickly shows whether a value converts to the target type.
• Add variable validation blocks to turn a deep type error into a clear, early message.

Related

• OpenTofu Error: ‘Invalid function argument’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Missing required argument’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Unsupported argument’ — Cause, Fix, and Troubleshooting Guide