Troubleshooting¶

Common issues and how to resolve them.

Configuration¶

Config file not found¶

Error: configuration file not found: .terratidy.yaml

TerraTidy looks for .terratidy.yaml in the current directory. Create one with terratidy init or specify a path with --config.

Invalid config syntax¶

Error: loading config: parsing YAML: ...

Run terratidy config validate to check your configuration file for syntax errors, invalid values, or missing required fields.

No engines enabled¶

Warning: no engines are enabled

At least one engine must be enabled. Check your config or profile to ensure enabled: true is set for at least one engine.

File Discovery¶

No HCL files found¶

No HCL files found

TerraTidy processes .tf, .hcl, and .tfvars files. Check that:

• You're running from the correct directory
• Your files have the correct extension
• Files aren't in a skipped directory (node_modules, vendor, .terraform, .terragrunt-cache)

--changed requires git¶

Error: not a git repository; --changed requires git

The --changed flag uses git to detect modified files. Run from within a git repository, or omit the flag to check all files.

Plugin Issues¶

Unsupported rule type¶

Error: unsupported rule type: bash (use go, rego, or yaml)

The init-rule command supports go, rego, and yaml types. Bash rules must be created manually.

Bash rule not executable¶

Error: plugin script is not executable

Bash rules must be executable. Fix with:

chmod +x .terratidy/plugins/my-rule.sh

Plugin loading errors¶

Check that:

• Plugin directories exist and are readable
• Go plugins (.so) are compiled for the correct platform
• YAML rules have valid syntax
• Bash scripts produce valid JSON output

LSP Issues¶

Server not starting¶

# Test if server starts
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | terratidy lsp

Check that TerraTidy is in your PATH and the configuration file is valid.

No diagnostics appearing¶

• Ensure the file is saved (diagnostics trigger on save)
• Check engine configuration in .terratidy.yaml
• Verify severity threshold isn't filtering findings
• Test the LSP server manually: echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | terratidy lsp

Performance¶

Slow on large repositories¶

• Use --changed to only check modified files
• Enable --parallel for the check command
• Disable engines you don't need (--skip-lint, --skip-policy)
• Use a profile with fewer engines for local development
• The cache (5-minute TTL, 1000 entries) helps with repeated runs

TFLint not found¶

Warning: TFLint not found in PATH

The lint engine falls back to built-in rules when TFLint is not installed. To use TFLint:

# Install TFLint
brew install tflint  # macOS
# or
curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh | bash

Exit Codes¶

If you're getting unexpected exit code 1, check the severity of your findings. Only error-severity findings cause a non-zero exit. Use --severity-threshold error to ignore warnings and info.