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

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 and inspecting the skill logs in .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).	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 under engines.node. If you encounter ERR_UNSUPPORTED_ESM_URL or similar module errors, upgrade your environment:

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:

npm ci

This forces a clean install of the exact versions declared in 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:

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 (derived from instructions in 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 contain helper functions that return structured JSON error objects. When the scraper cannot locate a required DOM node, you will see:

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

// 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) or when the AI generates duplicate imports.

Cleaning Stale Worktrees

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

# 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 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 – Declares Node engine requirements and pinned dependency versions.
• AGENTS.md – Central source of truth for AI agent instructions and worktree management.
• .github/skills/clone-website/SKILL.md – Contains the /clone-website command definition and error-handling logic.
• src/lib/utils.ts – Provides the cn() utility used throughout generated UI components; errors here indicate corrupted component generation.
• 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 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 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. 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 to include a custom User-Agent header or proxy settings.

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