How to fix Error: Invalid string encoding in Terraform

TerraformBEGINNERMEDIUM

Terraform requires UTF-8 encoded configuration files and string values. When you use non-UTF-8 characters or improperly encoded files, Terraform throws an invalid string encoding error. Fix this by ensuring proper file encoding and using appropriate Terraform functions for special characters.

What this error means

Terraform is a configuration language that strictly requires UTF-8 character encoding for all files and string values. When Terraform parses your configuration (.tf files, template files, or variable values) and encounters invalid UTF-8 sequences or non-UTF-8 encoded content, it rejects the input with an encoding error. This error commonly occurs when: - Configuration files are saved in non-UTF-8 encodings (UTF-16, Windows-1252, etc.) - Template files contain non-UTF-8 characters - Binary data is passed to functions expecting text strings - String values contain invalid character sequences The Terraform parser is strict about encoding because configuration must be portable across all operating systems and environments.

How to fix "Error: Invalid string encoding"

1Check and fix file encoding in your editor

Ensure all .tf files use UTF-8 encoding (without BOM). In most editors:

VS Code:
- Click the encoding indicator in the bottom-right (e.g., "UTF-8")
- Select "Reopen with Encoding" > "UTF-8"
- If using "UTF-8 with BOM", switch to "UTF-8"

Sublime Text:
- File > Save with Encoding > UTF-8

Visual Studio:
- File > Advanced Save Options > UTF-8 without signature

After changing encoding, save the file and re-run Terraform.

2Validate file encoding from command line

Use the file command (Linux/macOS) or similar tools to check encoding:

bash

# Check file encoding
file -i main.tf

# Output should show: charset=utf-8
# If you see iso-8859-1, utf-16, or others, you need to convert

Convert to UTF-8 if needed:

bash

# Convert from Windows-1252 or other encoding to UTF-8
iconv -f ISO-8859-1 -t UTF-8 main.tf > main.tf.new
mv main.tf.new main.tf

# Or use dos2unix to fix line endings and encoding
dos2unix main.tf

3Remove BOM (Byte Order Mark) if present

Some editors save UTF-8 files with a BOM (3 bytes: EF BB BF), which Terraform rejects. Remove it:

bash

# Check for BOM
hexdump -C main.tf | head -1

# If first line shows "ef bb bf", you have a BOM. Remove it:
sed '1s/^[[:space:]]*//' main.tf > main.tf.new
mv main.tf.new main.tf

# Or using a text editor: save as UTF-8 WITHOUT BOM

4Use filebase64() for binary or non-UTF-8 content

If you need to include content that isn't UTF-8 text, use filebase64() instead of file():

hcl

# Instead of this (fails if file isn't UTF-8):
content = file("./binary-data.bin")

# Use this:
content = filebase64("./binary-data.bin")

This reads the file as binary and Base64-encodes it, bypassing UTF-8 validation.

5Use jsonencode() for complex string values

When building JSON strings with special characters, use jsonencode() instead of string concatenation:

hcl

# Instead of this (can create invalid JSON):
env_vars = "{\"name\": \"${var.name}\"}"

# Use this:
env_vars = jsonencode({
  name = var.name
})

jsonencode() ensures proper escaping and valid UTF-8 output.

6Re-save template files in UTF-8

If using templatefile() with .tpl files:

bash

# Check template file encoding
file -i template.tpl

# Convert if needed
iconv -f ISO-8859-1 -t UTF-8 template.tpl > template.tpl.new
mv template.tpl.new template.tpl

Then update your Terraform code:

hcl

content = templatefile("./template.tpl", {
  var1 = "value1"
})

How to fix Error: Invalid string encoding in Terraform

What this error means

Typical symptoms

Common causes

How to fix "Error: Invalid string encoding"

Advanced notes

Related errors

Official resources & further reading