How to fix Error: Invalid string encoding in Terraform

TerraformBEGINNERMEDIUMUpdated Dec 31, 2025· 139 views

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.

Quick fix

Fixes Error: Invalid string encoding

# 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
  1. Check and fix file encoding in your editor
  2. Validate file encoding from command line
  3. Remove BOM (Byte Order Mark) if present
  4. Use filebase64() for binary or non-UTF-8 content
terraform — error
# 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
Error: Invalid string encoding

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.

Typical symptoms

  • Terraform plan or apply fails immediately with 'Invalid string encoding' error
  • Error mentions specific line/column in your .tf file
  • Configuration worked before but breaks after editing in certain editors
  • Error occurs even though the file looks correct when opened
  • File contains special characters or non-ASCII text that appears valid in your editor

Common causes

  1. Configuration files saved in UTF-16, UTF-8 with BOM, or other non-UTF-8 encodings (common on Windows with some editors)
  2. Template files (.tpl, .ps1, etc.) created with non-UTF-8 encoding
  3. Binary data or non-text content passed to string interpolation or file() functions
  4. Invalid UTF-8 sequences in heredoc strings or multiline strings
  5. Files created by PowerShell or other tools that default to non-UTF-8 encoding

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"
})

Advanced notes

Terraform's strict UTF-8 requirement stems from the need for portability. Configuration must work identically on Windows, macOS, Linux, and in CI/CD pipelines. UTF-8 is the only encoding that meets this universal requirement.

For PowerShell users on Windows: PowerShell often uses UTF-16 encoding by default. When creating .tf files via PowerShell redirection (e.g., "content" > file.tf), explicitly set encoding:

powershell
# Correct way to create .tf files in PowerShell
$content | Out-File -FilePath "main.tf" -Encoding UTF8

This ensures proper encoding across all platforms and tools.

Frequently asked questions

What does "Error: Invalid string encoding" mean?
Terraform is a configuration language that strictly requires UTF-8 character encoding for all files and string values. 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. ) - 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 do I fix "Error: Invalid string encoding"?
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 causes "Error: Invalid string encoding"?
Configuration files saved in UTF-16, UTF-8 with BOM, or other non-UTF-8 encodings (common on Windows with some editors) Template files (.tpl, .ps1, etc.) created with non-UTF-8 encoding Binary data or non-text content passed to string interpolation or file() functions
Is the "Error: Invalid string encoding" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading