# How to Troubleshoot Common Errors with the AI Website Cloner: Complete Guide

> Troubleshoot common AI website cloner errors. Learn to fix Node version mismatches, DOM selector issues, and Git conflicts with this comprehensive guide. Get your cloner working now.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Most AI website cloner failures stem from Node version mismatches, missing DOM selectors, or Git worktree conflicts, all of which can be resolved by verifying your environment against the template's requirements in [`package.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json) and inspecting the skill logs in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md).**

The **JCodesMore/ai-website-cloner-template** is a **Next.js 16** starter that orchestrates a multi-phase pipeline driven by an AI coding agent. Because the cloner is thinly wrapped around standard Node.js tooling, most errors surface as ordinary environment or build problems that can be diagnosed by tracing the execution through its five distinct phases.

## Understanding the AI Website Cloner Pipeline

The cloner processes websites through a sequential pipeline. Pinpointing which phase fails helps you troubleshoot common errors faster.

| Phase | What It Does | Typical Failure Points |
|-------|--------------|------------------------|
| **Reconnaissance** | Takes screenshots, extracts design tokens, scrolls/hovers the target site. | Network time‑outs, CORS blocks, or missing headless‑browser binaries. |
| **Foundation** | Downloads assets, writes global CSS/Tailwind config, updates the `public/` folder. | Failed downloads, invalid file paths, or permission errors. |
| **Component Specs** | Generates spec markdown files under `docs/research/` (e.g., [`DESIGN_TOKENS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/DESIGN_TOKENS.md)). | Spec generation aborts if the DOM cannot be queried; see `Element not found` errors. |
| **Parallel Build** | Spawns a git worktree per component, runs `npm run build` in each. | TypeScript compilation errors, missing dependencies, or mismatched Next.js versions. |
| **Assembly & QA** | Merges worktrees, runs visual diff against the original site. | Merge conflicts, lint failures, or Playwright browser crashes. |

## Dependency and Environment Issues

The template enforces strict runtime requirements. Violations here cause immediate failures before any cloning begins.

### Node Version Mismatch

The project requires **Node ≥ 24** as specified in [`package.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json) under `engines.node`. If you encounter `ERR_UNSUPPORTED_ESM_URL` or similar module errors, upgrade your environment:

```bash
nvm use 24

# or

nvm install 24

```

### Package Lock Drift

The template pins exact versions of `next` (16.2.1), `react` (19.2.4), and **Tailwind 4**. If you manually edited dependencies, restore the lockfile:

```bash
npm ci

```

This forces a clean install of the exact versions declared in [`package-lock.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package-lock.json), preventing "module not found" errors during the **Parallel Build** phase.

## Build and TypeScript Errors

When the AI generates components in temporary worktrees, TypeScript and Tailwind configuration issues surface immediately.

### Missing Type Definitions

Ensure `@types/react` and `@types/node` are present in `devDependencies`. If the compiler reports "Could not find a declaration file for module," install the types:

```bash
npm install --save-dev @types/react @types/node

```

### Tailwind v4 Syntax Errors

The template uses **Tailwind 4**, which introduced the `@layer` and `@apply` changes. If the build fails with CSS-related errors, verify that the generated [`tailwind.config.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/tailwind.config.ts) (derived from instructions in [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md)) follows the new v4 API rather than legacy v3 syntax.

## Runtime Errors in AI Skills

The skill scripts located in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) contain helper functions that return structured JSON error objects. When the scraper cannot locate a required DOM node, you will see:

```json
{ "error": "Element not found: " + selector }

```

### Fixing Selector Failures

1. **Check the target page** – Some sites load content lazily; increase wait times or manually scroll before scraping.
2. **Update the selector** – Inspect the page in Chrome DevTools and adjust the CSS selector directly in the skill file.

For example, if the original selector fails:

```typescript
// In .github/skills/clone-website/SKILL.md
/* Failing selector */
const btn = document.querySelector('.my-old-button');

/* Fixed selector */
const btn = document.querySelector('button[data-action="primary"]');

```

## Asset Download and Network Failures

During the **Foundation** phase, the download script performs batched parallel fetches. Errors manifest as:

```

Error: Failed to download https://example.com/logo.svg (status 403)

```

### Resolution Steps

- Verify the URL is publicly accessible without authentication.
- If the site blocks automated requests, configure a custom `User-Agent` header or route traffic through a proxy in the skill configuration.

## Git Worktree and Merge Conflicts

The **Parallel Build** phase uses **git worktrees** to isolate component builds. Conflicts arise when two components edit the same file (e.g., [`globals.css`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/globals.css)) or when the AI generates duplicate imports.

### Cleaning Stale Worktrees

If you encounter merge conflicts or "directory already exists" errors:

```bash

# List active worktrees

git worktree list

# Remove a stale worktree

git worktree remove <path>

# Prune all stale worktrees

git worktree prune

# Re-run the clone command

/clone-website https://example.com

```

Reference the worktree management logic in [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) for the specific cleanup commands used by the AI agent.

## Visual QA and Playwright Errors

The final **Assembly & QA** step runs screenshot comparisons using Playwright. If the visual diff never clears or hangs:

- Ensure `playwright` is installed as a dev dependency and can launch Chromium.
- Disable GPU acceleration or skip browser checks: `PLAYWRIGHT_SKIP_BROWSER_CHECK=1`.

## Key Source Files for Debugging

Keep these file paths accessible when troubleshooting:

- **[`package.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json)** – Declares Node engine requirements and pinned dependency versions.
- **[`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md)** – Central source of truth for AI agent instructions and worktree management.
- **[`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md)** – Contains the `/clone-website` command definition and error-handling logic.
- **[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)** – Provides the `cn()` utility used throughout generated UI components; errors here indicate corrupted component generation.
- **[`src/app/page.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/app/page.tsx)** – Entry page for the cloned site; useful for debugging layout issues.
- **`scripts/sync-skills.mjs`** – Updates the skill across all supported agents; run this if you modify skill logic.

## Summary

- **Verify Node 24** is active before running any commands to avoid module resolution errors.
- **Use `npm ci`** instead of `npm install` to respect the template's exact version pins for Next.js 16 and Tailwind 4.
- **Inspect [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md)** when you see "Element not found" errors, and update CSS selectors to match the live target site.
- **Clean git worktrees** with `git worktree prune` if parallel builds fail due to merge conflicts or stale directories.
- **Check network accessibility** of assets when download failures occur, and configure headers if the target blocks automated requests.

## Frequently Asked Questions

### Why am I getting "Element not found" errors during the reconnaissance phase?

This error originates in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) when the scraper cannot locate a DOM node with the specified CSS selector. Fix it by inspecting the target site in Chrome DevTools and updating the selector in the skill file to match the actual rendered HTML, or by adding wait times to account for lazy-loaded content.

### How do I resolve Git worktree merge conflicts during the parallel build?

The parallel build phase creates temporary worktrees for each component. If conflicts occur, list active worktrees with `git worktree list`, remove stale ones with `git worktree remove <path>`, and run `git worktree prune` to clean up. Then re-run the `/clone-website` command.

### What Node.js version is required for the AI website cloner?

The template requires **Node.js 24 or higher**, as declared in the `engines.node` field of [`package.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json). Running on Node 22 or lower will cause ESM module errors and dependency installation failures.

### How do I fix 403 Forbidden errors when downloading assets?

The asset download script in the skill file performs parallel fetches that may be blocked by the target server's bot protection. Verify the URL is publicly accessible, and if necessary, modify the fetch configuration in [`.github/skills/clone-website/SKILL.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.github/skills/clone-website/SKILL.md) to include a custom `User-Agent` header or proxy settings.