🛠️ Troubleshooting & Debugging Guide

This guide covers the most frequent technical hurdles encountered when developing with the Instant Ship™ scaffold.

0. 🚑 Operational Protocol: Leveraging the Bug Matrix (Read This First)

Goal: Locate and fix issues using our "Captured Ghost" archives before debugging from scratch.

We maintain a strict log of resolved technical debts in docs/instantship/bug_records.md. This is your first line of defense.

The 3-Step Resolution Workflow

Capture the Symptom (观察症状)
- Console Error: e.g., Minified React error #525 or ReferenceError: process is not defined.
- Behavior: e.g., "White Screen on load" or "404 when refreshing a specific page".
Pattern Match (查阅档案)
- Open docs/instantship/bug_records.md.
- Search for your specific error code or keyword.
- Identify the unique [FIX-ID].
Execute Protocol (执行修复)
- Go to the "3. Solution Implementation" section of that specific record.
- Copy the code snippet exactly. These fixes are architecturally validated.

Common Symptom Map

Symptom	Probable Cause	Target Record
White Screen (No Render)	React Version Mismatch / Importmap Issue	`[FIX-002]`
`process is not defined`	Missing Environment Shim	`[FIX-002]` (Phase B)
404 on Refresh (Cloudflare)	Missing `_redirects` config	`[FIX-001]`
Routing Fails (AI Studio)	Blob URL Security / Origin Mismatch	`[FIX-001]`

1. The "White Screen of Death" (React Error #525)

Symptoms: The console shows Error #525 or mentions a Suspense mismatch. Cause: This is almost always caused by "Multiple React Instance Clash." If a library (like TanStack or i18next) pulls in its own version of React instead of using the host instance, the React Dispatcher breaks. Fix:

Check index.html importmap. Ensure every library has ?external=react,react-dom appended.
Verify all React-related imports use the exact same version (e.g., 19.2.3).

2. "process is not defined"

Symptoms: App crashes immediately with a ReferenceError. Cause: Modern libraries often check process.env.NODE_ENV which doesn't exist in the browser. Fix: Ensure the process shim is present in the <head> of your index.html:


html
<script>window.process = { env: { NODE_ENV: 'development' } };</script>

3. 404 on Page Refresh (Cloudflare)

Symptoms: Navigating works fine, but refreshing a URL like /blog returns a Cloudflare 404. Cause: Single Page Apps (SPA) need the server to redirect all paths to index.html. Fix: Ensure public/_redirects contains /* /index.html 200.

4. Routing Fails in AI Studio / Sandbox

Symptoms: Clicking a link does nothing or throws an Origin/Security error. Cause: Security policies on blob: or usercontent.goog domains block pushState. Fix: The scaffold automatically switches to HashHistory in these environments. If you are forcing a history type, check isSandbox logic in index.tsx.

5. Metadata/SEO Not Updating

Symptoms: Social shares show old titles or descriptions. Cause: Helmet might be competing with static tags. Fix: Use the <SEO /> component exclusively and ensure site.config.ts is updated. Run npm run build to regenerate the sitemap.

Troubleshooting Guide