How I Fixed the “Large Files Detected” Error When Pushing a Terraform Project to GitHub

When working with Terraform, you may run into this GitHub error:

This message means GitHub is blocking your push because one or more files in your repository exceed its 100MB upload limit.

This error is common among Terraform beginners and even experienced engineers because of how Terraform organizes provider binaries. GitHub rejects any file larger than 100MB, and Terraform providers typically weigh between 200MB–500MB.

In this article, I’ll walk you through exactly why it happens, how I fixed it, and how you can prevent it from ever happening again.

Why This Happens

Terraform downloads provider binaries into:

.terraform/

If you run:
git add .

before adding .terraform to .gitignore, Git starts tracking these massive files.

Even if you delete the folder later, the large files remain in your Git history, and GitHub scans the entire history during a push.
If any file is over 100MB, GitHub blocks the push.

Step 1: Add .terraform to .gitignore

Then:

git add .gitignore
git commit -m "Add Terraform ignores files"

Step 2: Remove .terraform From Git History

Even after ignoring, GitHub still rejects the push because the massive files are stored in old commits. To fix this, we use a powerful tool:
git-filter-repo.

git filter-repo is a powerful and versatile tool for rewriting Git repository history. It is a Python script designed to be a faster, more capable, and more user-friendly alternative to git filter-branch

To install the git filter-repo on my machine (wsl on windows) I used the following commands

sudo apt update 
sudo apt install git-filter-repo   

run:
git filter-repo --version
to check if the installation was successful, it should print a version like this

Then clean your history:

git filter-repo --force --path .terraform/ --invert-paths

This removes all .terraform files from all past commits.

Step 3: Force Push the Cleaned Repo

The commit history has changed, you need to force push to upload the cleaned repository to Github without the large files
git push --force

This takes care of the large file error.

Terraform Git Best Practices

Never commit:

• .terraform/
• terraform.tfstate
• terraform.tfstate.backup
• provider binaries

Conclusion

This error is very common for Terraform beginners and even experienced engineers.
The fix is straightforward:

1. Ignore .terraform
2. Clean the Git history with git filter-repo
3. Force-push the cleaned repository

Taking the time to clean your repo ensures you maintain a lightweight, secure, and professional Terraform project.