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.
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.
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.
Use the file command (Linux/macOS) or similar tools to check 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 convertConvert to UTF-8 if needed:
# 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.tfSome editors save UTF-8 files with a BOM (3 bytes: EF BB BF), which Terraform rejects. Remove it:
# 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 BOMIf you need to include content that isn't UTF-8 text, use filebase64() instead of file():
# 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.
When building JSON strings with special characters, use jsonencode() instead of string concatenation:
# 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.
If using templatefile() with .tpl files:
# 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.tplThen update your Terraform code:
content = templatefile("./template.tpl", {
var1 = "value1"
})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:
# Correct way to create .tf files in PowerShell
$content | Out-File -FilePath "main.tf" -Encoding UTF8This ensures proper encoding across all platforms and tools.
Error: Error rendering template: template not found
How to fix "template not found" error in Terraform
Error: Error generating private key
How to fix 'Error generating private key' in Terraform
Error creating Kubernetes Service: field is immutable
How to fix "field is immutable" errors in Terraform
Error: Error creating local file: open: permission denied
How to fix "Error creating local file: permission denied" in Terraform
Error: line endings have changed from CRLF to LF
Line endings have changed from CRLF to LF in Terraform