How to fix Error: Invalid UTF-8 sequence in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 140 views

Terraform fails when reading files with invalid UTF-8 encoding, BOM markers, or binary content. This guide helps you identify the cause and fix encoding issues in your HCL configuration files.

Quick fix

Fixes Error: Invalid UTF-8 sequence

# Instead of:
locals {
  binary = file("archive.zip")  # ERROR

  # Use:
  binary_encoded = filebase64("archive.zip")  # Works
}
  1. Check your file encoding in your editor
  2. Remove UTF-8 BOM if present
  3. Re-create the file in a proper text editor
  4. Use filebase64() for binary files
terraform — error
# Instead of:
locals {
  binary = file("archive.zip")  # ERROR
  # Use:
  binary_encoded = filebase64("archive.zip")  # Works
}
Error: Invalid UTF-8 sequence

What this error means

When Terraform encounters a file with invalid UTF-8 byte sequences, it stops processing and throws an "Invalid UTF-8 sequence" error. This occurs when the `file()` or `templatefile()` functions attempt to read files that aren't properly UTF-8 encoded. UTF-8 is the standard text encoding for Terraform HCL files. Files saved in legacy encodings (like Windows-1252 or ISO-8859-1), corrupted binary files, or those with a Byte Order Mark (BOM) prefix will cause this error. The Terraform parser strictly validates UTF-8 compliance before processing your configuration.

Typical symptoms

  • Error appears during `terraform plan` or `terraform apply`
  • File functions like `file()` or `templatefile()` fail unexpectedly
  • Reading configuration files or templates produces parsing errors
  • Files created in PowerShell or Windows editors show encoding issues
  • Hidden special characters appear at the start of HCL files

Common causes

  1. File saved with UTF-8 encoding with BOM (Byte Order Mark) prefix, common when saving from VS Code or Windows editors
  2. File encoded in legacy character sets (Windows-1252, ISO-8859-1) instead of UTF-8
  3. File corrupted or contains mixed encoding with invalid UTF-8 sequences
  4. Attempting to read binary files (archives, images) using `file()` or `templatefile()` functions
  5. File created from PowerShell with non-standard encoding settings

How to fix "Error: Invalid UTF-8 sequence"

1Check your file encoding in your editor

Most modern text editors allow you to view and change file encoding. In VS Code, click the "UTF-8" indicator in the bottom status bar to see and change encoding options.

Ensure your .tf files are saved as UTF-8 without BOM. This is the default in most editors but may be overridden if you explicitly set encoding options.

2Remove UTF-8 BOM if present

If your file has a UTF-8 BOM, you'll see a special '' or 'ï' character at the very beginning when opened in a hex editor. Most editors have a way to remove the BOM.

In VS Code:
1. Open the file
2. Click "UTF-8" in the status bar
3. Select "UTF-8 with BOM" to see if it's enabled
4. Switch to "UTF-8" (without BOM) to remove it
5. Save the file

3Re-create the file in a proper text editor

If the encoding is still problematic, the simplest fix is to re-create the file:

1. Open your problematic .tf file
2. Copy all the content
3. Create a new file (ensuring it's UTF-8)
4. Paste the content
5. Delete the old file and save the new one

Use text editors like VS Code, Sublime Text, or Vim. Avoid Notepad on Windows, which often uses system encoding instead of UTF-8.

4Use filebase64() for binary files

If you're trying to read binary content (zip archives, encrypted files, images), the file() function cannot handle it. Use filebase64() instead:

hcl
# Instead of:
locals {
  binary = file("archive.zip")  # ERROR

  # Use:
  binary_encoded = filebase64("archive.zip")  # Works
}

For providers that need binary content, use attributes like content_base64 instead of content.

5Validate and format your configuration

After fixing the encoding, validate your Terraform configuration:

bash
terraform fmt -recursive       # Auto-format all .tf files
terraform validate            # Check syntax and provider validity

The terraform fmt command also helps ensure consistent formatting and can catch some encoding issues.

6Check for legacy encodings in your codebase

If you have multiple files, check for encoding issues across your project:

bash
# On Linux/Mac, check file encoding:
file *.tf | grep -i "utf"

# On Windows, use PowerShell (ensure UTF-8):
Get-ChildItem *.tf | ForEach-Object { $_.FullName }

Convert files from other encodings using iconv (Linux/Mac) or online tools. Ensure all .tf, .tfvars, and related files use UTF-8 without BOM.

Advanced notes

UTF-8 and Character Encoding in Terraform:

Terraform applies Unicode Normalization Form C (NFC) to all string inputs. This means that strings with equivalent representations are normalized to a canonical form. If the exact byte sequence matters (for binary data), providers may support base64-encoded variants (content_base64, source_base64) to bypass encoding assumptions.

Windows Encoding Differences:
On Windows systems, the default system encoding is CP1252 (Windows Latin-1), not UTF-8. If you have UTF-8 characters in your configuration (like descriptions or resource names), Windows Terraform may fail differently than on Linux. Always ensure files are explicitly saved as UTF-8 on Windows.

Multibyte Character Truncation:
In rare cases, when Terraform plan output contains very long IDs with multibyte characters (like emoji or international characters), the plan truncates output at 80 bytes without respecting character boundaries. This can create invalid UTF-8 in the plan file itself. Upgrade Terraform to the latest version to resolve this edge case.

Frequently asked questions

What does "Error: Invalid UTF-8 sequence" mean?
When Terraform encounters a file with invalid UTF-8 byte sequences, it stops processing and throws an "Invalid UTF-8 sequence" error. This occurs when the file() or templatefile() functions attempt to read files that aren't properly UTF-8 encoded. UTF-8 is the standard text encoding for Terraform HCL files.
How do I fix "Error: Invalid UTF-8 sequence"?
Terraform fails when reading files with invalid UTF-8 encoding, BOM markers, or binary content. This guide helps you identify the cause and fix encoding issues in your HCL configuration files.
What causes "Error: Invalid UTF-8 sequence"?
File saved with UTF-8 encoding with BOM (Byte Order Mark) prefix, common when saving from VS Code or Windows editors File encoded in legacy character sets (Windows-1252, ISO-8859-1) instead of UTF-8 File corrupted or contains mixed encoding with invalid UTF-8 sequences
Is the "Error: Invalid UTF-8 sequence" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading