🚨 The Incident

It was supposed to be a routine deployment. I pushed my new Hugo portfolio to Cloudflare Pages, expecting a green success checkmark within seconds.

Instead, the build failed immediately with this critical error:

Error: Pages only supports up to 20,000 files in a deployment. Ensure you have specified your build output directory correctly.

I checked my project root. It looked clean. Just a few Markdown files, a config file, and a theme. How could a simple static site contain 22,633 files?

🕵️‍♂️ The Investigation

I ssh’ed into my development environment (Termux on Android — yes, I maintain my infrastructure on mobile) and started digging.

First, I needed to confirm if Git was actually tracking that many files. I ran the following command:

git ls-files | wc -l

Output:

22633

Okay, the files were definitely there. But where were they hiding?

I used the find command to locate directories containing an unusually high number of files (more than 1000):

find . -type d -exec sh -c 'count=$(find "$0" -type f | wc -l); [ "$count" -gt 1000 ] && echo "$0: $count files"' {} \;

The Culprit: static/awsome_fonts/.

It turned out I had blindly copied a full raw FontAwesome directory containing thousands of individual SVG, LESS, and SCSS files that I didn’t even need for production.

✂️ The Surgical Fix

Deleting the folder locally using rm wasn’t enough because Git has a long memory. If I just deleted them from the disk, Git might still try to track the deletion event for every single file, or keep them in history. I needed to remove them from the Git Index to stop Cloudflare from fetching them during the clone process. Step 1: The Purge I used git rm with the –cached flag to unstage the files effectively.

# Remove from Git index and filesystem recursively
git rm -r --cached static/awsome_fonts
rm -rf static/awsome_fonts

Step 2: The Commit I committed the “diet” plan to the repository history.

git commit -m "chore: Remove unused font assets to fix 20k file limit"

Step 3: Verification Before pushing again, I ran the counter one last time to be sure:

git ls-files | wc -l

New Output:

111

From 22,633 to 111. A 99.5% reduction in file count.

🚀 The Result

I pushed the changes to the main branch. Cloudflare Pages picked up the commit immediately.

Previous Build Time: Failed.

New Build Time: 18 seconds.

Status: ✅ Success.

💡 The Lesson

“Just because you have bandwidth, doesn’t mean you should use it.”

In the age of node_modules and massive asset libraries, it is easy to unintentionally bloat your repository. Always audit your static assets before committing. A lean repository is a happy repository.

Built & Documented by Radi.