tflint: Lint Terraform for Errors and Bad Practice
tflint analyzes Terraform code for errors, deprecated syntax, and provider-specific problems that terraform validate misses.
terraform validate only checks that config is internally consistent. TFLint goes further: invalid instance types, unsupported attributes, and naming conventions, with rules that understand each cloud provider.
What it does
tflint loads the Terraform in the current directory, applies the core ruleset plus any installed plugin rulesets, and reports issues. It exits 0 when clean, 2 when issues are found, and 1 on an internal error. --recursive lints every subdirectory, which suits a monorepo of modules.
Common usage
tflint
# lint every module in the repo
tflint --recursive
# only fail on errors, not warnings/notices
tflint --minimum-failure-severity=error
# machine output for a report
tflint --format=jsonOptions
| Flag | What it does |
|---|---|
| --recursive | Lint the current directory and all subdirectories |
| --format <fmt> | default, json, checkstyle, junit, compact, sarif |
| --minimum-failure-severity <lvl> | error, warning, or notice as the failing threshold |
| --only <rule> | Run a single named rule |
| --config <file> | Use a specific .tflint.hcl |
| --call-module-type <type> | all, local, or none: which modules to inspect |
In CI
Run tflint --init first (plugins are not bundled), then tflint --recursive. The exit code drives the gate: 2 means findings, so the job fails as intended. Set --minimum-failure-severity=error if you want warnings reported but not blocking. tflint does not call any cloud API, so it is safe to run without credentials.
Common errors in CI
"Failed to load configurations; Plugin ... not installed" means you skipped tflint --init. "Reference to undeclared input variable" is a real finding, not a tool bug. A clean repo that suddenly fails with exit 2 after a version bump often hit a newly added default rule; pin the TFLint version in CI.