Real-world Debugging Struggle with Next.js and Cloudflare Pages: From Git LFS to CSP Errors

August 10, 2025 Next.js Cloudflare Pages Git Debug Troubleshooting

Real-world Debugging Struggle with Next.js and Cloudflare Pages: From Git LFS to CSP Errors

Hello! In the world of web development, encountering unexpected errors is a daily occurrence. This time, I'm documenting a series of challenging debugging processes faced when deploying a Next.js project to Cloudflare Pages. From Git LFS errors to Next.js build errors, hydration errors, and finally, Cloudflare Pages-specific CSP/Illegal invocation errors, I'll share the journey to their resolution.

1. Battle with Git LFS Errors: Erasing a Huge node_modules from History

The Origin of the Problem

When attempting to push a Next.js project to GitHub, I encountered the following error:

remote: error: File <project_name>/node_modules/... is 129.50 MB; this exceeds GitHub's file size limit of 100.00 MB

This was because the node_modules folder was mistakenly included in Git's tracking, exceeding GitHub's file size limit (100MB).

First Attempt: .gitignore and git rm --cached

As a standard solution, I added /node_modules to .gitignore and removed it from the index with git rm -r --cached ..

Add /node_modules to .gitignore
git add .
git commit -m "fix: Add .gitignore"

However, the push failed. It turned out that GitHub rejects pushes as long as large files remain in Git's history.

Struggle with BFG Repo-Cleaner (and Giving Up)

To clean up the history, I tried BFG Repo-Cleaner, recommended by Git's official documentation.

Create a mirror clone

git clone --mirror https://github.com/<username>/<repository_name>.git
cd <repository_name>.git

Running BFG (failed despite trying various options)

java -jar ../bfg-x.x.x.jar --delete-folders node_modules # Specify folder name
java -jar ../bfg-x.x.x.jar --strip-blobs-bigger-than 100M # Specify size
java -jar ../bfg-x.x.x.jar -D <file_name> # Specify file name
...all failed with "No refs to update - no dirty commits found??"

Even after running git gc to optimize the repository, the situation didn't change. I concluded that this was a rare case that BFG couldn't solve and gave up.

Last Resort: The Forbidden git filter-branch

As a last resort, I used Git's standard git filter-branch.

【Important】This operation rewrites Git history, so be sure to back up your repository before executing.

Execute in the project root

git filter-branch --force --index-filter 'git rm -r --cached --ignore-unmatch <Next.js_project_directory_name>/node_modules' --prune-empty --tag-name-filter cat -- --all

Delete backup references and optimize the repository For PowerShell:

Remove-Item -Recurse -Force .git\refs\original

For Linux/macOS/Git Bash:

rm -rf .git/refs/original/

Delete reflogs and unnecessary data

git reflog expire --expire=now --all
git gc --prune=now

Force push

git push origin --force --all
git push origin --force --tags

With this operation, the huge files were finally removed from the history, and the push to GitHub succeeded.

2. Chain of Next.js Build Errors: From Syntax to Types

No sooner had the Git issue been resolved than the deployment to Cloudflare Pages failed. New errors appeared one after another in the build logs.

Syntax Errors

• Cause: Apostrophes within strings (e.g., App's) caused JavaScript syntax errors. Missing JSX closing tags.
• Solution: Correct basic syntax errors, such as enclosing strings in double quotes and adding closing tags.

TypeScript Type Errors

• Cause:
  • Did not consider the possibility of getBlogPost returning null.
  • Attempted to assign a Contentful Entry type to an array initialized as useState([]).
  • console.log remained in JSX.
  • Numbers were passed to setAttribute.
  • Incorrect type inference for the return value of document.createElement.
• Solution: Strengthen null checks, explicitly specify types like useState<Entry<any>[]>([]), remove console.log, type conversion with String(), type assertion with as HTMLScriptElement.

Cloudflare Pages Specific Configuration Errors

• Edge Runtime setting: Missing export const runtime = 'edge'; in some routes.
• Node.js Compatibility: The nodejs_compat flag was not enabled in Cloudflare Pages settings.

By fixing these errors one by one, the Next.js build finally succeeded.

3. The Abyss of Runtime Errors: CSP and Illegal invocation

Despite a successful build, accessing the site displayed an Application error, and the browser console showed Content Security Policy of your site blocks the use of 'eval' in JavaScript and TypeError: Illegal invocation.

Battle with eval Errors

• Cause Isolation:
  • Disabling dangerouslySetInnerHTML in RichTextRenderer made the eval error disappear, but content was not displayed.
  • Disabling DisqusComments or Google AdSense did not make the eval error disappear.
  • Even completely emptying Contentful blog posts did not make the eval error disappear.
• Conclusion: The eval error was likely caused by JavaScript within Contentful's rich text rendered via RichTextRenderer's dangerouslySetInnerHTML, or by Cloudflare Pages' internal processing.

Battle with Illegal invocation Errors

• Cause Isolation:
  • Problems occurred with DisqusComments's DOM operations (createElement, appendChild) and the loss of this context when calling DISQUS.reset.
  • Attempts to fix by explicitly binding this using call or bind did not resolve the error.
  • Ultimately, even after completely removing DisqusComments, the Illegal invocation error persisted, reconfirming that RichTextRenderer's dangerouslySetInnerHTML was likely the cause.

Final Solution (Provisional)

The eval and Illegal invocation errors were likely caused by compatibility issues between the Cloudflare Pages Workers environment and dangerouslySetInnerHTML, or by specific content within Contentful's rich text.

• Re-disabling dangerouslySetInnerHTML in RichTextRenderer: Although blog content will no longer be displayed, the site itself was restored to a state where it displays without errors.
• This resolved the eval and Illegal invocation errors.

Summary

This debugging session tested a wide range of knowledge and patience, from Git history manipulation to the Next.js build system, TypeScript's type system, and Cloudflare Pages' unique runtime environment.

• Git: Always include node_modules in .gitignore. Rewrite history carefully with git filter-branch.
• Next.js: Thoroughly resolve type errors. Don't ignore warnings, such as priority for Image components.
• Cloudflare Pages:
  • For subdirectory configurations, root directory settings are essential.
  • For Next.js dynamic features, export const runtime = 'edge'; and the nodejs_compat flag are essential.
  • dangerouslySetInnerHTML and external scripts (AdSense, Disqus, etc.) are prone to eval and Illegal invocation errors in the Cloudflare Workers environment.

Ultimately, although the display of blog content was temporarily disabled, we were able to restore the entire site to a state where it displays without errors. Moving forward, we need to fundamentally re-evaluate how Contentful rich text is rendered or consider relaxing CSP (not recommended).