# Purpose of the Debug Cache in WeChat Article Exporter (store/v2/debug.ts)

> Learn about the WeChat Article Exporter's debug cache. This IndexedDB table stores failed download HTML for offline debugging without impacting the main cache. Perfect for developers.

- Repository: [公众号文章工具箱/wechat-article-exporter](https://github.com/wechat-article/wechat-article-exporter)
- Tags: internals
- Published: 2026-05-26

---

**The debug cache is a dedicated IndexedDB table in [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) that stores raw HTML blobs from failed article downloads to enable offline debugging without contaminating the main content cache.**

The wechat-article-exporter project isolates problematic HTTP responses using a specialized persistence layer distinct from the standard HTML cache. Implemented in [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts), this debug cache captures unparsable article content, preserving the exact server responses that trigger parsing exceptions or error states. By separating these diagnostic artifacts from successful downloads stored in [`store/v2/html.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/html.ts), the system enables developers to inspect anti-scraping blocks, malformed HTML, or credential failures long after the original network request completes.

## What Is the Debug Cache?

The debug cache serves as a **diagnostic buffer** within the application's Dexie-based IndexedDB architecture. Unlike the primary `html` table that stores successfully processed articles, this table retains only exceptional cases where the download pipeline fails to extract valid metadata or content.

Key characteristics of the debug cache include:

- **Isolation of error data**: Failed downloads are segregated from successful cache entries to prevent data pollution
- **Blob persistence**: Raw HTML responses are stored as JavaScript Blob objects, preserving the exact byte-for-byte server response
- **Metadata retention**: Each entry includes the target URL, article title, WeChat fakeid, and error classification type

## Core Implementation Details

The implementation in [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) defines a minimal schema optimized for debugging workflows rather than high-volume storage.

### The DebugAsset Interface

Each debug entry conforms to the `DebugAsset` interface, which structures the metadata surrounding a failed download:

```typescript
interface DebugAsset {
  fakeid: string;      // WeChat article identifier
  type: string;        // Error classification (e.g., 'parse error', 'exception:...')
  url: string;         // Source URL of the failed request
  title: string;       // Article title for identification
  file: Blob;          // Raw HTML response as binary blob
}

```

*Source:* [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) lines 3-9 define this interface with explicit typing for the Blob storage.

### Database Operations

The module exposes three primary functions for interacting with the `debug` table:

**`updateDebugCache(asset: DebugAsset)`**  
Inserts a new debug record within a Dexie transaction. This function is atomic and handles the IndexedDB write operation for persisting failed HTML blobs.

**`getDebugCache(url: string)`**  
Retrieves a single `DebugAsset` by its URL, enabling targeted inspection of specific failed downloads.

**`getDebugInfo()`**  
Returns the complete array of cached debug assets, typically used to populate a debug UI or diagnostic dashboard.

*Source:* Lines 15-32 in [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) implement these CRUD operations using Dexie transactions.

## When Failed Downloads Are Captured

The download pipeline in [`utils/download/Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/utils/download/Downloader.ts) populates the debug cache during two specific failure modes, distinguishing between parsing exceptions and explicit parser errors.

### Exception Scenarios

When the HTML downloads successfully but the parser throws an exception while extracting the comment ID, the system caches the response with a type indicating the specific exception context:

```typescript
// In utils/download/Downloader.ts
if (status === 'Exception' && !commentID) {
  await updateDebugCache({
    fakeid: article.fakeid,
    type: `exception:${commentID}`,
    url,
    title: article.title,
    file: blob,
  });
}

```

This scenario typically indicates server-side anti-scraping measures or unexpected HTML structure changes that prevent metadata extraction.

### Parse Error Scenarios

When the parser returns an explicit error status rather than throwing, the system categorizes the failure differently:

```typescript
if (status === 'Error') {
  await updateDebugCache({
    fakeid: article.fakeid,
    type: 'parse error',
    url,
    title: article.title,
    file: blob,
  });
}

```

*Source:* Lines 10-22 and 28-31 in [`utils/download/Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/utils/download/Downloader.ts) contain these conditional blocks that trigger debug cache updates.

## Working with the Debug Cache

Developers can interact with the debug cache programmatically to build diagnostic tools or manual recovery workflows.

### Storing Failed HTML Blobs

To manually capture a problematic response for later analysis, import the update function and persist the blob with appropriate metadata:

```typescript
import { updateDebugCache } from '~/store/v2/debug';

async function captureFailure(article: Article, url: string, blob: Blob) {
  await updateDebugCache({
    fakeid: article.fakeid,
    type: 'parse error',
    url,
    title: article.title,
    file: blob,
  });
}

```

### Retrieving All Debug Entries

To display a list of failed downloads in a debug UI, fetch the complete dataset using `getDebugInfo`:

```typescript
import { getDebugInfo } from '~/store/v2/debug';

async function displayDebugList() {
  const debugAssets = await getDebugInfo();
  
  debugAssets.forEach(asset => {
    console.log(`[${asset.type}] ${asset.title} – ${asset.url}`);
    // Create an object URL to preview the raw HTML
    const previewUrl = URL.createObjectURL(asset.file);
    window.open(previewUrl, '_blank');
  });
}

```

*Source:* The `getDebugInfo` function returns the full array of stored debug assets as implemented in [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) lines 30-32.

### Querying Specific Failed URLs

For targeted debugging of a particular article, retrieve the specific entry by URL:

```typescript
import { getDebugCache } from '~/store/v2/debug';

async function inspectFailure(url: string) {
  const asset = await getDebugCache(url);
  if (asset) {
    const htmlText = await asset.file.text();
    console.error(`Failed HTML content (${asset.type}):`, htmlText);
    // Analyze the raw HTML to determine why parsing failed
  }
}

```

*Source:* `getDebugCache` performs lookups by URL in [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) lines 26-28.

## Key Files in the Debug System

| File | Role |
|------|------|
| [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) | Defines `DebugAsset` interface and provides CRUD helpers for the debug cache table |
| [`utils/download/Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/utils/download/Downloader.ts) | Populates debug cache when HTML parsing fails with exceptions or errors |
| [`store/v2/html.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/html.ts) | Primary cache for successfully parsed articles (contrast with debug cache) |
| [`store/v2/db.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/db.ts) | Dexie database configuration where the `debug` table is registered |

## Summary

- The **debug cache** in [`store/v2/debug.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/debug.ts) is an IndexedDB-backed storage mechanism specifically for failed article downloads.
- It stores raw HTML as **Blob objects** to preserve exact server responses for forensic analysis.
- The cache is populated from [`utils/download/Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/utils/download/Downloader.ts) during two failure modes: parsing **exceptions** and explicit **parse errors**.
- Functions **`updateDebugCache`**, **`getDebugCache`**, and **`getDebugInfo`** provide the complete interface for persisting and retrieving diagnostic data.
- This separation prevents **cache pollution** in the main HTML table while enabling offline debugging of anti-scraping blocks or malformed responses.

## Frequently Asked Questions

### What is the difference between the debug cache and the regular HTML cache?

The regular HTML cache in [`store/v2/html.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/store/v2/html.ts) stores successfully parsed articles for offline reading, while the debug cache exclusively retains failed downloads that could not be parsed. The debug cache acts as a diagnostic buffer, keeping error cases segregated to avoid contaminating the working dataset with corrupted or unparsable content.

### How can I view the contents of a failed download stored in the debug cache?

Retrieve the specific entry using `getDebugCache(url)` or enumerate all failures with `getDebugInfo()`, then convert the stored Blob to text using `blob.text()` or create an object URL with `URL.createObjectURL(blob)` to render the HTML in a preview window. This allows inspection of the exact server response that caused the parsing failure.

### When does the WeChat Article Exporter automatically save data to the debug cache?

The exporter automatically populates the debug cache when the download pipeline in [`utils/download/Downloader.ts`](https://github.com/wechat-article/wechat-article-exporter/blob/main/utils/download/Downloader.ts) encounters either a JavaScript exception during HTML parsing (status `'Exception'`) or an explicit parser error state (status `'Error'`). Both scenarios preserve the raw HTTP response blob along with metadata including the URL, title, and WeChat fakeid.

### Can I manually add entries to the debug cache for testing purposes?

Yes, you can import `updateDebugCache` from `~/store/v2/debug` and programmatically insert any `DebugAsset` object containing a fakeid, error type, URL, title, and Blob. This is useful for testing debug UI components or preserving problematic responses encountered during development without triggering actual download failures.