Sync Error Handling
Relevant source files
The following files were used as context for generating this wiki page:
The Sync Error Handling system within the claude-code-docs project is designed to maintain the integrity of the documentation mirror by preventing partial or corrupted updates. The primary goal is to ensure that transient network failures or malformed source data do not lead to accidental mass deletions or broken links in the GitHub repository.
The system operates on a "fail-fast" principle where any fetch failure during the synchronization process throws an error and aborts the execution. This prevents the CI/CD pipeline from committing a partial tree of documentation, ensuring that the docs/ directory always represents a complete and valid state of the source documentation.
Sources: sync.ts:1-7, README.md:14-17
Sync Architecture and Resilience
The synchronization logic is centralized in sync.ts and relies on several mechanisms to handle errors during the lifecycle of a sync run.
Retry Logic and Timeouts
The system implements a retry mechanism for all HTTP requests to mitigate transient network issues. Each request is attempted up to a defined number of times with an exponential backoff strategy.
The logic for this is contained within the fetchText function, which uses a sleep interval that increases with each attempt.
Sources: sync.ts:10-11, sync.ts:43-57
Manifest Validation
Before proceeding with the documentation download, the system validates the manifest retrieved from llms.txt. If the manifest contains fewer than 10 pages, it is treated as a parsing failure or a corrupted source, and the process is aborted to prevent a "mass deletion" commit.
| Configuration Constant | Value | Description |
|---|---|---|
RETRIES | 3 | Maximum number of attempts for a single URL fetch. |
CONCURRENCY | 10 | Number of simultaneous page downloads. |
Min Page Threshold | 10 | Minimum required pages in manifest to avoid sync abort. |
Sources: sync.ts:10-11, sync.ts:66-68
Link Rewriting and Integrity
To prevent broken links when documentation is viewed locally or on GitHub, the system performs URI transformation. It maps site-absolute paths (e.g., /en/sub-agents) to relative local paths (e.g., ./sub-agents.md) if the target exists in the knownSlugs set derived from the manifest.
Fallback Mechanism
If a link refers to a page that is not being mirrored, the system falls back to the canonical absolute URL on code.claude.com. This ensures that even if a page is missing from the local mirror, the link remains functional.
Sources: sync.ts:18-41, sync.ts:74-76
Hook and Plugin Error Handling
Beyond the core synchronization, the repository provides hooks for the Claude Code CLI. These hooks include defensive programming and validation to handle unexpected inputs during tool execution.
URL Transformation Validation
The rewrite-docs-url.sh script acts as a PreToolUse hook. It includes specific error-handling logic to ignore URLs that do not match the expected documentation pattern, ensuring it doesn't interfere with unrelated WebFetch operations.
- Silent Exit: The script exits with code 0 without outputting JSON if the URL is not a Claude Code documentation link.
- Path Protection: It explicitly avoids rewriting the docs root or files that already have extensions (like
.mdor images) to prevent circular redirects or corrupted paths. - Test Suite: A dedicated test script,
rewrite-docs-url.test.sh, validates these edge cases to prevent regressions in URL rewriting logic.
Sources: hooks/rewrite-docs-url.sh:7-35, hooks/rewrite-docs-url.test.sh:1-40
Skill Fallback Strategy
The SKILL.md defines a fallback strategy for AI agents attempting to access the documentation. If the primary ask CLI tool is unavailable, the skill instructions provide a sequence of fallback methods:
- npx/bunx: Run the tool via a package runner.
- Grep: Fall back to basic text search if semantic search tools (
csp) are missing. - WebFetch: Manually fetch the manifest and pages from the live site if the local mirror cannot be resolved.
Sources: skills/claude-code-docs/SKILL.md:15-61
Summary
Sync Error Handling in this project is characterized by a robust set of safeguards: retry logic for network resilience, threshold validation for manifest integrity, and a fail-fast execution model to protect the repository from corrupted commits. These mechanisms, combined with a tiered fallback strategy for consumers of the documentation, ensure high availability and reliability of the documentation mirror.