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

TerraformINTERMEDIATEMEDIUMUpdated Dec 30, 2025· 128 views

This Terraform error occurs when you provide an incompatible type (like a string, number, or object) where a list of strings is expected. Fix it by understanding Terraform's type system and using the correct list syntax in your configuration.

Quick fix

Fixes Error: Unsuitable value type - list of string required

  1. Understand what type is expected
  2. Check if you're passing a list incorrectly
  3. Verify variable types are defined correctly
  4. Handle single values that need to be lists
  5. Use for_each or count for complex list operations
terraform — error
# Error: Unsuitable value type - list of string required
Error: Unsuitable value type - list of string required

What this error means

The "Unsuitable value type - list of string required" error is Terraform's way of telling you that an argument, variable, or attribute expects a list of strings, but you've provided something else. This is a type mismatch error. Terraform has a strict type system with specific expectations for each argument. When Terraform encounters a value that doesn't match the expected type and can't automatically convert it, it raises this error. This commonly happens with: - Passing a single string where a list is expected - Wrapping an already-list value in extra brackets - Using an incompatible data type (number, bool, map, etc.) where a list of strings is required - Configuration syntax errors or incorrect variable references

Typical symptoms

  • Terraform plan or apply fails with 'Unsuitable value type' error
  • Error message specifically mentions 'list of string required'
  • Configuration worked in older Terraform versions but now fails
  • Error points to a specific argument that should accept a list

Common causes

  1. Passing a single string value directly instead of wrapping it in a list (e.g., name = var.single_string instead of name = [var.single_string])
  2. Wrapping an already-list value in extra brackets (e.g., instances = [var.instance_list] when var.instance_list is already a list)
  3. Using the wrong data type entirely (number, bool, object, or map) where a list of strings is expected
  4. Leftover syntax from Terraform v0.11 or earlier that is incompatible with v0.12+
  5. Incorrect variable type definition (e.g., variable defined as string when it should be list(string))

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

1Understand what type is expected

First, identify which argument or variable is causing the error. Check the error message and the resource documentation to understand what type it expects.

If the error says 'list of string required', that means the argument should be a list of strings like:

["value1", "value2", "value3"]

Check the provider documentation or resource schema for the specific argument that's failing.

2Check if you're passing a list incorrectly

Look at your configuration and check if you're wrapping a list in extra brackets.

WRONG (extra brackets):
instances = [var.instance_list]

CORRECT (use the list directly):
instances = var.instance_list

If you want to combine or manipulate lists, use list functions or the concat() function instead of wrapping.

3Verify variable types are defined correctly

In your variables.tf, ensure that any variable you're passing to a list-of-strings argument is actually defined as list(string).

Example of a properly defined list variable:

variable "allowed_users" {
 type = list(string)
 description = "List of allowed usernames"
}

If you have a single string that needs to become a list, either:
1. Define the variable as list(string) and wrap the value in square brackets when using it
2. Wrap the single value in a list at the point of use: allowed_users = [var.single_user]

4Handle single values that need to be lists

If you have a single string value that needs to be used where a list of strings is expected, convert it to a list:

variable "single_user" {
 type = string
}

resource "example_resource" "main" {
 # Convert single string to a list of one string
 users = [var.single_user]
}

Or use Terraform functions to manipulate the data:

resource "example_resource" "main" {
 # Use tolist() to ensure it's a list
 users = tolist([var.single_user])
}

5Use for_each or count for complex list operations

If you need to apply a list of values to multiple resources or arguments, use for_each or count with proper list indexing:

variable "users" {
 type = list(string)
}

resource "example_resource" "by_user" {
 for_each = toset(var.users)

# Each iteration gets one string from the list
 username = each.value
}

6Validate your configuration

Run terraform validate to check for syntax errors before applying:

terraform validate

If you want to see what types Terraform has determined for your values, use terraform console:

terraform console
> var.my_variable
> type(var.my_variable)

This helps diagnose type mismatches quickly.

Advanced notes

Type conversion in Terraform: Terraform will automatically convert compatible types when possible. For example, if an argument expects a list(string), Terraform can convert a tuple of mixed types like ["a", 15, true] to ["a", "15", "true"] by converting elements to strings.

However, this automatic conversion doesn't work for incompatible types. You cannot convert an object to a string or a map to a list without explicit conversion functions.

For Terraform v0.12+ users upgrading from v0.11: The error "list of string is required" often appears after upgrading because v0.12 removed support for redundant extra brackets around interpolations. Code that previously worked like instances = [var.instance_list] now needs to be instances = var.instance_list.

Frequently asked questions

What does "Error: Unsuitable value type - list of string required" mean?
The "Unsuitable value type - list of string required" error is Terraform's way of telling you that an argument, variable, or attribute expects a list of strings, but you've provided something else. This is a type mismatch error. Terraform has a strict type system with specific expectations for each argument.
How do I fix "Error: Unsuitable value type - list of string required"?
This Terraform error occurs when you provide an incompatible type (like a string, number, or object) where a list of strings is expected. Fix it by understanding Terraform's type system and using the correct list syntax in your configuration.
What causes "Error: Unsuitable value type - list of string required"?
Passing a single string value directly instead of wrapping it in a list (e.g., name = var.single_string instead of name = [var.single_string]) Wrapping an already-list value in extra brackets (e.g., instances = [var.instance_list] when var.instance_list is already a list) Using the wrong data type entirely (number, bool, object, or map) where a list of strings is expected
Is the "Error: Unsuitable value type - list 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