# How to Debug Fetch Errors When Downloading Stitch Designs: A Complete Guide

> Debug Stitch design fetch errors by enabling verbose JSON output and checking Puppeteer browser logs. Learn how to resolve these non-fatal warnings efficiently.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-12

---

**Fetch errors during Stitch design downloads are non-fatal warnings captured in the `stats.warnings` array; enable verbose JSON output and inspect the Puppeteer browser logs to identify failing URLs.**

When downloading Stitch designs from the `google-labs-code/stitch-skills` repository, the system relies on a Puppeteer-driven snapshot script to inline external resources. This process executes native `fetch` calls inside a headless Chromium instance to download stylesheets, images, and CSS assets, but failures are silently logged by default, making debugging difficult without the right flags.

## Where Fetch Errors Occur in the Stitch Pipeline

The snapshot pipeline performs four distinct fetch operations that can fail. Each failure is caught and logged, but the script continues processing remaining assets.

### Stylesheet Inlining Failures

In [`plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts) (around lines 149–154), the script attempts to fetch external stylesheets using `await fetch(href)`. If the response is not `ok`, the stylesheet is skipped and a warning is pushed to `stats.warnings`.

### Image and Asset Fetching via `toDataUri`

Images, background URLs, SVG `<image>` references, video posters, and favicons are processed through the `toDataUri` helper injected into the page (around lines 159–165 in [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts)). This helper uses `await fetch(url, { mode: 'cors', credentials: 'same-origin' })`. When the fetch fails or returns a non-OK status, the function returns `null` and the asset is omitted from the final output.

### CSS `url()` Reference Resolution

Inside `<style>` blocks, the `toDataUri` function resolves CSS `url()` references (around lines 210–218). These fetches follow the same error handling pattern as images—failures are silently ignored but counted in `stats.cssUrls`.

### Inline HTML Image Extraction

The separate [`extract_inline_html.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/extract_inline_html.ts) script contains a `fetchAndEncode` helper used by the extract-inline-HTML skill. Located in [`plugins/stitch-design/skills/extract-static-html/scripts/extract_inline_html.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-static-html/scripts/extract_inline_html.ts), this helper catches errors and resolves with an empty string, causing the image to be dropped from the markdown without stopping the pipeline.

## How to Surface Hidden Fetch Failures

Because fetch errors are non-fatal by design, you must explicitly enable verbose output to see what failed.

### Enable Verbose JSON Output

The scripts forward browser console messages to Node via `page.on('console', …)`. Run the snapshot with the `--json` flag to dump the full `stats` object, which contains every warning string.

```bash
npx tsx snapshot.ts \
  --url http://localhost:5173 \
  --output .stitch/home.html \
  --json

```

The terminal will output a JSON block containing the `warnings` array:

```json
{
  "url": "http://localhost:5173",
  "output": "/path/to/.stitch/home.html",
  "sizeBytes": 342157,
  "stylesheets": 12,
  "images": 8,
  "cssUrls": 4,
  "warnings": [
    "Failed to inline stylesheet: https://cdn.example.com/theme.css (status 404)",
    "Failed to fetch image: https://cdn.example.com/logo.png (network error)"
  ],
  "durationMs": 8421
}

```

### Inspect the `stats.warnings` Array

After the run finishes, examine entries that mention specific URLs and HTTP status codes. Warnings are generated in three locations within [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts):

- **Stylesheet failures**: Lines 149–154
- **Image fetch failures**: Lines 159–165 inside `toDataUri`
- **CSS URL fetch failures**: Lines 210–218 inside `toDataUri`

### Verify Network Connectivity in Chromium

Because fetches execute **inside the headless Chromium instance**, they are affected by the browser’s network stack, not the Node process. Verify that the browser can reach the target host by opening the URL in a regular Chrome window or by adding a temporary `await page.waitForNavigation()` after navigating in your script.

### Increase Navigation Timeouts

The snapshot script caps each navigation at `Math.min(30000, opts.timeout - 5000)`. If large assets are being fetched slowly, raise the global timeout:

```bash
npx tsx snapshot.ts \
  --url http://localhost:5173 \
  --output .stitch/home.html \
  --timeout 120000

```

### Add Explicit Error Logging to `toDataUri`

For granular diagnostics, modify the injected code in [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts) (around lines 15–30) to add explicit `console.error` statements:

```typescript
toDataUri: async (url: string): Promise<string | null> => {
  try {
    const resp = await fetch(url, { mode: 'cors', credentials: 'same-origin' });
    console.error(`Fetching ${url} → ${resp.status}`);
    if (!resp.ok) return null;
    // ... rest of implementation
  } catch (e) {
    console.error(`Fetch error for ${url}:`, e);
    return null;
  }
},

```

Re-run the snapshot and inspect the browser console logs printed to your terminal to see the exact status code for each attempted fetch.

## Isolating Problematic URLs

### Validate Relative and Absolute URLs

The script skips URLs that start with `data:`, `http:`, `https:`, or `//`. If a relative URL is malformed, the parser may produce an empty string, causing a silent failure. Use the `--json` output to see which URLs were attempted and verify them against the source HTML.

### Test Single URLs with [`extract_inline_html.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/extract_inline_html.ts)

Run the `extract-inline-html` skill in isolation to determine if the issue lies in the page-side fetch implementation or network configuration:

```bash
npx tsx extract_inline_html.ts \
  --url https://example.com/broken-image.png

```

This script uses the same `fetchAndEncode` logic as the full pipeline but provides immediate feedback for a single resource.

## Summary

- **Fetch errors are non-fatal**: The [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts) script continues processing even when assets fail to load, logging warnings to `stats.warnings`.
- **Use `--json` output**: This reveals the complete `stats` object including all failed URLs and their failure modes.
- **Check Chromium network**: Fetches run inside the browser context, not Node, so verify connectivity from within the headless environment.
- **Modify `toDataUri`**: Inject `console.error` statements into the page-side helper (lines 15–30) to expose status codes for every fetch attempt.
- **Isolate with [`extract_inline_html.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/extract_inline_html.ts)**: Test individual URLs outside the full snapshot flow to verify network accessibility.

## Frequently Asked Questions

### Why are fetch errors silent by default in Stitch?

The tool is designed to be tolerant of flaky networks or missing assets, ensuring that partial design downloads succeed even when external resources are unavailable. This prevents temporary CDN issues from breaking the entire snapshot process, but it requires the `--json` flag to surface specific failure details.

### How can I see the exact HTTP status code for a failed fetch?

Add explicit error logging inside the `toDataUri` helper in [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts). By inserting `console.error(\`Fetching ${url} → ${resp.status}\`)` before the response check, the browser console will forward the status code to your Node terminal, revealing whether the failure is a 404, 403, or network timeout.

### Can I increase the timeout for slow-loading assets?

Yes. The snapshot script calculates the navigation timeout as `Math.min(30000, opts.timeout - 5000)`. Pass a higher value using the `--timeout` flag (in milliseconds) to allow more time for large images or slow stylesheets to download before Puppeteer aborts the request.

### What is the difference between [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts) and [`extract_inline_html.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/extract_inline_html.ts)?

[`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts) is the main Puppeteer entry point that walks the DOM and inlines all external resources using `fetch` calls injected into the page. [`extract_inline_html.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/extract_inline_html.ts) is a specialized helper used by the extract-inline-HTML skill that contains the `fetchAndEncode` function for fetching remote images referenced in design markdown, useful for testing single URLs in isolation.