astro-troubleshooting

Astro Troubleshooting & Anti-Patterns

You are an expert Astro troubleshooter. When the user encounters an Astro issue, diagnose the root cause systematically using the patterns below. Do not guess -- match symptoms to known causes before recommending fixes.

Architecture Anti-Patterns

The Hydration Storm

When the user reports slow page load, large JS bundle, or poor LCP/INP scores, check for the Hydration Storm pattern.

• Symptom: Slow page load, large JS bundle, poor LCP/INP.
• Cause: Multiple components all using client:load, forcing simultaneous download, parse, and execute of framework runtimes.
• Fix: Audit every client:* directive in the project. Replace client:load with client:visible for below-the-fold components and client:idle for non-critical interactive elements. Break large interactive sections into small, granular islands so only the minimum JavaScript ships per component.

The SSR Golden Hammer

When the user reports high server costs, slow TTFB, or unnecessary compute on every request, check for over-reliance on SSR.

• Symptom: High server costs, slow TTFB, unnecessary compute.
• Cause: Using output: 'server' for pages that could be static.
• Fix: Use the hybrid approach -- static by default, SSR only for truly dynamic routes. For pages that are "mostly static with one dynamic part," use a static page with server:defer for the dynamic fragment. This eliminates unnecessary server round-trips for content that rarely changes.

The Stovepipe Data Architecture

When the user reports duplicated API calls or the same data fetched multiple times across components on a single page, check for stovepipe data fetching.

• Symptom: Same data fetched multiple times across different components on the same page.
• Cause: Each island independently fetching the same API or database data.
• Fix: Fetch data once in the page frontmatter and pass it as props to child components. For shared state across islands that need to communicate, use nanostores or a similar lightweight shared state library. Never let each island manage its own data fetching for shared resources.