TerraformPilot

DevOps

Fix Terraform Error - HCL Syntax Unexpected Token

Fix HCL syntax errors: unexpected tokens, missing brackets, block definitions, and JSON vs HCL confusion. Common mistakes with code examples and fixes.

LLuca Berton2 min read

Quick Answer

#

HCL syntax errors come from missing brackets, extra commas, = signs in block headers, or mixing JSON and HCL syntax. Run terraform fmt to auto-fix formatting, and terraform validate to catch structural errors. Use an editor with HCL support for real-time feedback.

The Error

# 
Error: Invalid expression
 
  on main.tf line 12:
  Expected the start of an expression, but found an invalid expression token.
Error: Argument or block definition required
 
  on main.tf line 5, in resource "aws_instance" "web":
  An argument definition must not be given as a block.
Error: Unexpected token
 
  on main.tf line 8:
  Expected a comma or closing bracket, but got newline.

What Causes This Error

#

1. Equals Sign in Block Headers

# 
# BAD — = sign in resource block header
resource = "aws_instance" "web" {
}
 
# GOOD — no = sign
resource "aws_instance" "web" {
}

2. Missing or Extra Brackets

# 
# BAD — missing closing brace
resource "aws_instance" "web" {
  ami           = "ami-12345"
  instance_type = "t3.micro"
 
  tags = {
    Name = "web"
  # Missing } for tags AND resource
 
# GOOD
resource "aws_instance" "web" {
  ami           = "ami-12345"
  instance_type = "t3.micro"
 
  tags = {
    Name = "web"
  }
}

3. Trailing Commas in Lists

# 
# BAD in older Terraform (OK in 1.0+, but can confuse)
cidr_blocks = [
  "10.0.0.0/8",
  "172.16.0.0/12",
  "192.168.0.0/16",  # Trailing comma — usually OK but check version
]
 
# Object keys with commas (BAD)
tags = {
  Name = "web",       # BAD — no commas between HCL attributes
  Environment = "prod"
}
 
# GOOD — no commas in HCL blocks
tags = {
  Name        = "web"
  Environment = "prod"
}

4. JSON Syntax in .tf Files

# 
# BAD — JSON syntax in .tf file
{
  "resource": {
    "aws_instance": {
      "web": {
        "ami": "ami-12345"
      }
    }
  }
}
 
# GOOD — HCL syntax in .tf file
resource "aws_instance" "web" {
  ami = "ami-12345"
}
 
# JSON is valid in .tf.json files only

5. Arguments Outside Blocks

# 
# BAD — argument outside any block
ami = "ami-12345"
 
resource "aws_instance" "web" {
  instance_type = "t3.micro"
}
 
# GOOD — all arguments inside their block
resource "aws_instance" "web" {
  ami           = "ami-12345"
  instance_type = "t3.micro"
}

6. Missing Quotes Around Strings

# 
# BAD — unquoted string
resource "aws_instance" "web" {
  ami = ami-12345  # Missing quotes
}
 
# GOOD
resource "aws_instance" "web" {
  ami = "ami-12345"
}

How to Fix It

#

Solution 1: Auto-Format with terraform fmt

# 
# Format all files in the current directory
terraform fmt
 
# Format recursively (all subdirectories)
terraform fmt -recursive
 
# Check which files need formatting (dry run)
terraform fmt -check -recursive

Solution 2: Validate Syntax

# 
# Check for syntax and configuration errors
terraform validate
 
# If validate fails, fix the reported line first
# Errors cascade — fixing line 5 often fixes lines 10, 15, etc.

Solution 3: Use an Editor with HCL Support

# 
# VS Code — best HCL support
code --install-extension hashicorp.terraform
 
# JetBrains IDEs — built-in HCL support
# Install the "Terraform and HCL" plugin
 
# Vim/Neovim
# Use vim-terraform or nvim-lspconfig with terraform-ls

Solution 4: Check Bracket Matching

# 
# Count opening vs closing braces
grep -c '{' main.tf
grep -c '}' main.tf
# Numbers should match
 
# Find unmatched brackets with your editor's bracket matching feature
# VS Code: Ctrl+Shift+\ (jump to matching bracket)

Solution 5: Common Quick Fixes

#
ErrorCauseFix
Expected the start of an expressionMissing value after =Add the value: ami = "ami-12345"
Argument or block definition requiredStray text outside blocksMove inside a block or delete
Expected a comma or closing bracketMissing ] or }Close the collection
Invalid characterSmart quotes from copy-pasteReplace " " with "
Unexpected token after block definition= in block headerRemove the =

Troubleshooting Checklist

#
  1. ✅ Run terraform fmt — fixes most formatting issues
  2. ✅ Run terraform validate — check the specific line number
  3. ✅ Count { and } — do they match?
  4. ✅ Are there smart quotes ("") from copy-paste?
  5. ✅ Is there JSON syntax in a .tf file?
  6. ✅ Are there commas between HCL block attributes? (Remove them)
  7. ✅ Is there an = in a resource or data block header?

Prevention Tips

#
  • Use terraform fmt in CI — reject PRs with formatting issues
  • Install HCL editor extensions — real-time syntax highlighting catches errors immediately
  • Copy from docs, not blogs — blog posts often have smart quotes and formatting artifacts
  • Use terraform validate as a pre-commit hook — catches errors before they're committed
  • Keep one resource per file for large projects — easier to spot bracket mismatches
#

Conclusion

#

HCL syntax errors are usually simple: missing brackets, wrong quotes, or JSON-style commas in HCL blocks. Run terraform fmt to fix formatting, terraform validate to find structural issues, and use an editor with HCL support to prevent them in the first place. Fix the first error reported — later errors often cascade from the first.

#Terraform#Troubleshooting#DevOps#Error Fix#Infrastructure as Code

Share this article

Related articles