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

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 (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). 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 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, 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.

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

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

{
  "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:

• 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:

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 (around lines 15–30) to add explicit console.error statements:

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

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

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 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: 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. 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 and extract_inline_html.ts?

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}