When Codex Broke My Site: A Frontend Debugging Walkthrough

How the Incident Started

Users reported that JavaGuide felt sluggish on older machines, while the author experienced smoother performance on a new M‑series Mac. The discrepancy suggested high client‑side parsing, execution, and rendering costs, prompting the author to ask Codex to analyze the site.

Codex identified several concrete issues:

Main bundle was large, adding significant initialization pressure.

Long articles contained excessive HTML, DOM nodes, and code blocks.

Numerous Mermaid diagrams caused slow rendering on older devices.

Local search index was heavy for a large site, increasing download and memory usage.

Some global components performed unnecessary DOM queries and layout reads.

The author had Claude review these findings, confirming their validity.

Initial Optimizations

Based on the analysis, the author applied several optimizations:

Disabled local search in favor of DocSearch.

Lazy‑loaded Mermaid diagrams.

Deferred loading of certain layout buttons.

Adjusted CDN and Nginx cache settings.

Turned off unnecessary first‑screen capabilities.

Although the direction was correct, the deployment caused a new problem: after publishing, many pages rendered blank, with intermittent refreshes sometimes fixing the view.

Symptoms After Deployment

The console repeatedly showed:

Hydration completed but contains mismatches.

Failed to fetch dynamically imported module

Requests to /assets/*.js returned 404.

Initially this looked like a classic cache issue—old HTML referencing old JS chunks that had been deleted.

First Round Fix: Cache and Deployment Chain

The deployment script cleared the site directory and moved the new dist folder in place. For static sites this works, but Vite/VuePress generate hashed asset filenames. Deleting the old /assets directory meant that any lingering old HTML or CDN edge caches still referenced the now‑missing hashed files, resulting in 404 errors.

To mitigate this, the author adjusted the caching strategy:

HTML is not cached; the entry point updates immediately after a release.

Hashed JS and CSS assets receive long‑term cache headers.

CDN follows the origin Cache‑Control header instead of imposing a fixed TTL.

Old assets are retained for 30‑60 days to accommodate browsers still using previous HTML.

This resolved the 404 errors but the page remained white.

AI‑Powered Deep Dive

Using the Computer Use capability, the AI opened the Tencent Cloud EdgeOne console, read the current acceleration configuration, changed the node cache TTL to “follow source Cache‑Control”, set the default policy to “no‑store” for HTML, saved the settings, and verified the response headers with curl. This automated interaction went beyond typical AI Q&A.

After confirming the CDN settings, the author used browser automation provided by the AI to launch a clean environment, serve the local dist folder, and capture console logs. The static build still produced a blank page, indicating the problem lay in the build output rather than the CDN.

Isolating the Root Cause

The author progressively removed top‑level components to see which triggered the white screen. The culprit was an image‑preview component that used VuePress's Teleport to mount a preview overlay directly under body. While the idea reduced the first‑screen bundle size, the component participated in server‑side rendering (SSR). During hydration, the server‑rendered structure differed from the client‑rendered one, causing the root node to become an empty comment and the page to stay blank.

Fix: render the Teleport only after the component is mounted on the client, ensuring SSR and client hydration produce identical markup.

After applying this change, a local rebuild succeeded, and both the homepage and the /ai/ page displayed correctly in the automated browser.

Key Takeaways

CDN caching is often blamed first, but the real issue may be frontend hydration mismatches.

When using hashed assets, retain old files for a reasonable period to avoid 404s from stale HTML.

AI agents can accelerate troubleshooting—checking configs, running commands, automating browsers—but engineers must still steer the investigation and validate directions.

Avoid large, simultaneous changes; incremental adjustments simplify root‑cause isolation.

When modifying production pipelines with AI, verify each stage before proceeding.