How to fix Error: Unsuitable value type - map of string required in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 30, 2025· 136 views

This error occurs when you assign a value to a Terraform variable or argument that expects a map(string) type, but you're providing a map with non-string values (numbers, booleans, lists, etc.). Terraform requires all values in a map(string) to be strings, and automatically converting incompatible types fails validation.

Quick fix

Fixes Error: Unsuitable value type - map of string required

variable "my_map" {
  type = map(string)  # This requires all values to be strings
}
  1. Verify the variable or argument type declaration
  2. Convert all map values to strings
  3. Use tostring() function for dynamic values
  4. For templatefile(), ensure tags/variables are strings
terraform — error
variable "my_map" {
  type = map(string)  # This requires all values to be strings
}
Error: Unsuitable value type - map of string required

What this error means

Terraform uses strict type checking for variables and resource arguments. When a variable or argument is declared with type map(string), it means the map must contain only string key-value pairs. If you attempt to assign: - A map with numeric values (e.g., {port = 8080}) - A map with boolean values (e.g., {enabled = true}) - A map with nested structures (e.g., {config = {nested = "value"}}) - A map with lists (e.g., {tags = ["tag1", "tag2"]}) Terraform's type system detects the mismatch and raises this error. This is a validation error that occurs during plan or apply phases, preventing invalid configurations from being applied.

Typical symptoms

  • Terraform plan or apply fails with 'Unsuitable value type - map of string required' error
  • Error message appears when passing variable values or local maps to functions like templatefile()
  • Module input validation fails when passing map values that don't match the declared type
  • Error occurs even though the values appear to be correct in your configuration

Common causes

  1. Passing a map with non-string values to a variable or argument expecting map(string)
  2. Using numeric values (123) instead of string values ("123") in map literals
  3. Using boolean values (true) instead of string values ("true") in map assignments
  4. Passing nested maps or objects when the function expects map(string)
  5. Variable default values containing mixed types (some strings, some numbers)
  6. Using templatefile() with tags or variables parameter that contains non-string values

How to fix "Error: Unsuitable value type - map of string required"

1Verify the variable or argument type declaration

Check the variable definition or resource/module argument that's causing the error. Look for the type constraint:

hcl
variable "my_map" {
  type = map(string)  # This requires all values to be strings
}

If the type is explicitly declared as map(string), then all values must be strings. If you need to store different types, consider using map(any) or a more specific object type instead.

2Convert all map values to strings

Wrap all non-string values in quotes to convert them to strings:

hcl
# Before (causes error):
variable "config" {
  type = map(string)
  default = {
    port     = 8080          # number, not string
    enabled  = true          # boolean, not string
  }
}

# After (works correctly):
variable "config" {
  type = map(string)
  default = {
    port    = "8080"         # converted to string
    enabled = "true"         # converted to string
  }
}

All values must be enclosed in quotes to be treated as strings.

3Use tostring() function for dynamic values

If you're assigning computed or variable values, use the tostring() function to ensure conversion:

hcl
variable "port_number" {
  type = number
}

variable "config" {
  type = map(string)
  default = {
    port = tostring(var.port_number)  # Convert number to string
  }
}

locals {
  enabled_flag = true
  config_map = {
    enabled = tostring(local.enabled_flag)  # Convert boolean to string
  }
}

This explicitly converts values to their string representation.

4For templatefile(), ensure tags/variables are strings

When using templatefile(), the variables parameter must be a map(string):

hcl
# Before (may cause error):
content = templatefile("${path.module}/template.tpl", {
  port = 8080        # This is a number
})

# After (correct):
content = templatefile("${path.module}/template.tpl", {
  port = "8080"      # Explicitly a string
})

This applies to local.file, template_file data source, and similar functions.

5Change type to map(any) if mixed types are needed

If you genuinely need to store multiple types in a map, change the type declaration:

hcl
# Instead of:
variable "config" {
  type = map(string)
}

# Use:
variable "config" {
  type = map(any)  # Allows any type as values
}

However, use this sparingly as it reduces type safety. For known structures, prefer explicit object types:

hcl
variable "config" {
  type = object({
    port    = number
    enabled = bool
    tags    = list(string)
  })
}

Advanced notes

Type strictness in Terraform 0.12+: Terraform enforces strict type checking to prevent configuration errors. Unlike earlier versions, Terraform 0.12 introduced proper type inference and validation.

Implicit conversions: While Terraform automatically converts between some types (e.g., number to string in certain contexts), this doesn't apply to map values. All map values must explicitly match their declared type.

Working with modules: This error often appears when passing local values or variables to module inputs. Always check the module's variable type declarations in the module's variables.tf file.

Type inference with default values: If a variable has no explicit type but has a default value, Terraform infers the type. Mixed-type defaults will trigger this error.

Frequently asked questions

What does "Error: Unsuitable value type - map of string required" mean?
Terraform uses strict type checking for variables and resource arguments. When a variable or argument is declared with type map(string), it means the map must contain only string key-value pairs. , {tags = ["tag1", "tag2"]}) Terraform's type system detects the mismatch and raises this error.
How do I fix "Error: Unsuitable value type - map of string required"?
This error occurs when you assign a value to a Terraform variable or argument that expects a map(string) type, but you're providing a map with non-string values (numbers, booleans, lists, etc.). Terraform requires all values in a map(string) to be strings, and automatically converting incompatible types fails validation.
What causes "Error: Unsuitable value type - map of string required"?
Passing a map with non-string values to a variable or argument expecting map(string) Using numeric values (123) instead of string values ("123") in map literals Using boolean values (true) instead of string values ("true") in map assignments
Is the "Error: Unsuitable value type - map of string required" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading