Skip to main content

Troubleshooting Report: Server Onboarding Runtime and Performance Incident

This report documents the issues encountered during 01. Server-onboarding migration and the exact fixes applied.

1. Incident Summary​

Scope​

  • Docusaurus docs migration for: docs/server/linux-server/01. Server-onboarding
  • Production site affected: brain.id86.net

User-visible impact​

  • Runtime crashes in browser
  • Chunk loading failures (ChunkLoadError)
  • Slow response and high VPS resource usage

2. Symptoms Observed​

A. React runtime error​

  • Should have a queue. This is likely a bug in React.
  • Stack pointed to @easyops-cn/docusaurus-search-local SearchBar component.

B. Chunk load failures​

  • Repeated errors loading chunk files such as __props---docs-category-...js and content---docs-...js.
  • Browser attempted old chunk names that no longer existed after rebuild.

C. MDX compilation failures​

  • Invalid MDX table row in:
    • docs/server/linux-server/01. Server-onboarding/shared-core/vps-security-hardening/network-layer/ufw-overview.mdx
  • Broken image path in:
    • docs/server/linux-server/01. Server-onboarding/wordpress/vps-security/db-hardening/move-wpconfigphp-to-upper-folder.mdx
  • Missing Tabs/TabItem imports in:
    • docs/server/linux-server/01. Server-onboarding/shared-core/network-optimization/google-bbr.mdx
    • docs/knowledge/docusaurus/01. Setup/mdx-preview-setup-guide.mdx

D. High CPU and memory usage​

  • docusaurus container repeatedly recompiling (webpack cycles)
  • CPU spikes and multi-GB RAM usage while running in development mode

3. Root Cause Analysis​

Root cause 1: Search plugin compatibility/runtime instability​

  • Local search plugin (@easyops-cn/docusaurus-search-local) triggered runtime hook issues with current dependency set.

Root cause 2: Invalid/missing MDX assets and component imports​

  • MDX parser failed on malformed syntax and unresolved local image references.
  • JSX components in MDX (Tabs, TabItem) were used without imports.

Root cause 3: Stale browser/session chunk references​

  • After content/config changes, client still requested old chunk names.
  • Some chunk URL requests returned HTML login pages (Cloudflare Access), which looked like chunk failures in app runtime.

Root cause 4: Serving mode mismatch​

  • Dev-style runtime (docusaurus start) is expensive in production and can trigger frequent recompilation under edits/restarts.

4. Fixes Applied​

A. Search plugin disabled​

  • Removed plugin config from docusaurus.config.js.
  • Removed @easyops-cn/docusaurus-search-local from package.json.
  • Cleared .docusaurus cache and restarted container.

B. MDX syntax and asset fixes​

  • Fixed malformed row in ufw-overview.mdx.
  • Removed unresolved image references in move-wpconfigphp-to-upper-folder.mdx.
  • Added missing imports:
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

C. Production serving mode applied​

  • Updated package.json start script to static serving mode:
"start": "docusaurus serve --host 0.0.0.0 --port 3000"
  • Ensured static build exists and container serves build output.

D. Container normalization​

  • Recreated docusaurus container via compose to align runtime behavior.
  • Verified command and process mode inside container.

5. Validation Performed​

  • npm run build completed successfully inside container.
  • Container logs showed static serving mode:
[SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/
  • Resource usage normalized (low CPU + low memory compared to prior spikes).
  • Re-scan confirmed no remaining MDX files with missing Tabs/TabItem imports.

6. Operational Notes​

Why chunk errors can still appear temporarily​

  • Browser may cache old JS chunk names after deployment.
  • Cloudflare Access/session state can return HTML for stale chunk requests.

Recovery actions for frontend stale chunks​

  1. Hard refresh (Ctrl+Shift+R)
  2. Re-authenticate Cloudflare Access session
  3. Test in incognito
  4. Purge CDN cache if needed

Before restart/deploy​

sudo docker exec -w /app docusaurus npm run build

Restart service​

sudo docker restart docusaurus

Check health/logs​

sudo docker logs --since 2m docusaurus
sudo docker stats --no-stream docusaurus

If stale chunks persist on users​

  • Clear browser cache / force reload
  • Purge Cloudflare cache for affected assets/pages

8. Preventive Actions​

  • Pin Docusaurus/React versions (avoid latest in production).
  • Keep production container on static serve mode (build + serve workflow).
  • Add CI build check for MDX syntax and unresolved local media links.
  • Add lint/check for MDX component imports (Tabs, TabItem, custom JSX).