# How to Debug Rendering and Performance Issues Using Astro's Built-In Tools

> Debug Astro rendering and performance issues fast with built-in tools like Vite's dev overlay, ASTRO_DEBUG, and bundle analysis. Optimize your site efficiently.

- Repository: [Astro/astro](https://github.com/withastro/astro)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Astro provides first-class debugging capabilities through Vite's dev overlay, the ASTRO_DEBUG environment variable for SSR timing, the --analyze flag for bundle visualization, and built-in hydration warnings—all without requiring external dependencies.**

When building static and server-rendered applications with the `withastro/astro` framework, identifying bottlenecks requires deep visibility into both the build process and runtime behavior. Fortunately, Astro ships with comprehensive debugging tools that leverage its Vite-powered development server to help you debug rendering and performance issues using Astro's built-in tools without installing additional packages.

## Essential Debugging Tools Overview

Astro categorizes its debugging capabilities by the type of issue you're investigating. Each tool targets specific rendering or performance concerns:

**Component Rendering Errors**

The **dev overlay** (Vite error overlay) provides full stack traces, source file links, and a "Show component source" button directly in your browser when compilation fails.

**Client-Side Hydration Problems**

The `astro dev` console automatically warns about missing `client:*` directives, mismatched IDs, and hydration mismatches between server and client renders.

**Bundle Size Analysis**

The `astro build --analyze` command generates an interactive treemap visualization (similar to webpack-bundle-analyzer) showing exactly which modules contribute to JavaScript bloat.

**Server-Side Rendering Performance**

Setting `ASTRO_DEBUG=true` during development enables detailed timing logs for each route and component render, helping identify slow Astro components.

**Production Performance Auditing**

The `astro preview --open` command starts a production-like server that allows you to run Chrome DevTools Lighthouse audits against real-world Core Web Vitals metrics.

## Core Implementation Architecture

Understanding where these features live in the Astro source code helps you interpret their output and contribute fixes when needed.

### Dev Overlay Implementation

The browser error overlay is implemented in [`packages/astro/src/core/dev/devOverlay.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/core/dev/devOverlay.ts). This module listens for Vite compile errors, formats them for readability, and injects the overlay script into HTML responses. When you see a red error screen in development, this file is generating that UI.

### SSR Timing and Debug Logs

Server-side render timing is handled by [`packages/astro/src/runtime/server/dev/timing.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/runtime/server/dev/timing.ts). This file wraps each render call with `performance.now()` to measure execution time, aggregates per-route statistics, and writes formatted logs to your terminal when the `ASTRO_DEBUG` environment variable is set.

### Bundle Analysis Integration

The `--analyze` flag logic resides in [`packages/astro/src/cli/commands/build.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/cli/commands/build.ts). After Vite completes the production build, this command forks into `rollup-plugin-visualizer` to generate the [`dist/stats.html`](https://github.com/withastro/astro/blob/main/dist/stats.html) file containing the interactive bundle size treemap.

### Hydration Warning System

Client-side hydration diagnostics are emitted from [`packages/astro/src/runtime/client/hydration.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/runtime/client/hydration.ts). This module detects when components are rendered on the server but lack matching `client:*` directives on the client, printing console warnings that help you fix hydration mismatches.

### Preview Server for Auditing

The production preview server is implemented in [`packages/astro/src/cli/commands/preview.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/cli/commands/preview.ts). This starts a minimal static server that mirrors your production environment exactly, enabling you to run Lighthouse audits and test Core Web Vitals like CLS, LCP, and FID before deployment.

## Practical Debugging Commands

These specific command patterns help you debug rendering and performance issues using Astro's built-in tools in real-world scenarios.

### Basic Development with Error Overlay

Start the dev server to get instant feedback on compilation errors:

```bash
npm run astro dev

```

When errors occur, the browser displays a red overlay with full stack traces. Click the **Source** link to jump directly to the offending file.

### Detailed SSR Performance Timing

Enable debug logging to identify slow components during server-side rendering:

```bash
ASTRO_DEBUG=true npm run astro dev

```

Console output example:

```

→ /src/pages/index.astro rendered in 12.4 ms
→ Component Header (src/components/Header.astro) rendered in 3.1 ms
→ Total route time: 18.9 ms

```

### Bundle Size Analysis

Analyze JavaScript bloat after building:

```bash
npm run astro build -- --analyze

```

This generates [`dist/stats.html`](https://github.com/withastro/astro/blob/main/dist/stats.html) with an interactive treemap. Hover over blocks to see which components or libraries contribute most to the payload.

### Hydration Mismatch Detection

The dev server automatically warns about hydration issues:

```

[astro] Hydration mismatch: Component `Carousel` rendered on the server but has no matching `client:*` directive.

```

Fix by adding the appropriate directive:

```astro
<Carousel client:load />

```

### Production Performance Auditing

Test real-world performance before deployment:

```bash
npm run astro preview -- --open

```

This opens your production build at `http://localhost:4321`. Use Chrome DevTools Lighthouse to audit Core Web Vitals including CLS, LCP, and FID.

**Pro Tip:** When the bundle analyzer shows large third-party chunks, use the `client:only` directive to keep heavy libraries out of the server bundle while still loading them client-side:

```astro
<HeavyChartingLibrary client:only="react" />

```

## Summary

- **Start with `astro dev`** to leverage Vite's error overlay for immediate feedback on compilation and rendering errors.
- **Enable `ASTRO_DEBUG=true`** to capture detailed server-side render timing for each route and component.
- **Run `astro build --analyze`** to visualize bundle composition and identify JavaScript bloat sources.
- **Monitor console warnings** during development to catch hydration mismatches early and fix them with proper `client:*` directives.
- **Use `astro preview`** to run Lighthouse audits against production-like builds before deploying.

## Frequently Asked Questions

### How do I enable debug mode in Astro?

Set the `ASTRO_DEBUG` environment variable to `true` when starting the dev server:

```bash
ASTRO_DEBUG=true npm run astro dev

```

This activates detailed logging in [`packages/astro/src/runtime/server/dev/timing.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/runtime/server/dev/timing.ts), showing precise render times for each route and component in your terminal.

### What is the Astro dev overlay?

The dev overlay is a browser-based error interface implemented in [`packages/astro/src/core/dev/devOverlay.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/core/dev/devOverlay.ts). It intercepts Vite compilation errors and renders a full-screen overlay with stack traces, source file links, and a "Show component source" button, allowing you to click directly into the offending code.

### How can I analyze my Astro bundle size?

Run the build command with the `--analyze` flag:

```bash
npm run astro build -- --analyze

```

This generates [`dist/stats.html`](https://github.com/withastro/astro/blob/main/dist/stats.html) using logic from [`packages/astro/src/cli/commands/build.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/cli/commands/build.ts) and `rollup-plugin-visualizer`. The interactive treemap reveals which components or third-party libraries contribute most to your JavaScript payload.

### Why am I seeing hydration mismatch warnings?

Hydration warnings originate from [`packages/astro/src/runtime/client/hydration.ts`](https://github.com/withastro/astro/blob/main/packages/astro/src/runtime/client/hydration.ts) when a component is rendered on the server but lacks a corresponding `client:*` directive on the client. This indicates that Astro expected to hydrate interactive elements but couldn't find the matching client-side instructions. Resolve these by adding the appropriate hydration directive, such as `client:load` or `client:only`, to your component tags.