🗺️ n8n Sitemap Validator

✨ The problem it solves

Sitemaps are your source of truth for what your site should be serving — and they rot silently. Pages get deleted, routes change, certificates expire, and a 404 hides behind a redirect. Your crawlers might even pick up URLs that should never have been published in the first place.

Most people find out from Google Search Console — weeks later. This node runs the check now, on demand, as part of your automation:

• 🔁 Schedule a weekly SEO health-check workflow.
• ⚠️ Pipe the output into Slack / Email / n8n-formatted-notification the moment a broken link appears.
• 🧹 Run it before a site migration or relaunch to verify nothing breaks.
• 📊 Store results in a database and track link-health over time.

Give it a sitemap URL, get back one item per URL with its status, redirect chain, and a rollup summary — nothing to configure, everything to filter on.

✅ What it catches

Plus: it resolves sitemap indexes, nested sub-sitemaps, and gzip-compressed .xml.gz files automatically — no extra steps.

📦 Installation

Prerequisites: Node.js ≥ 18.10

There are two ways to install: automatic (recommended — a few clicks) and manual (copy the package into the folder where n8n loads custom nodes). Either way, restart n8n afterwards so the node shows up in the editor.

🤖 Automatic install

Method 1 — Install from inside n8n (recommended)

The easiest way; straight from the n8n UI:

1. Open your n8n admin panel and go to Settings → Community Nodes.
2. Click Install.
3. Search for and install the package n8n-nodes-sitemap-validator.
4. Restart n8n.

After the restart, the Sitemap Validator node appears in the editor under Transform.

Method 2 — Global install via npm

If you have shell access, install the package once on the system and it becomes available to every n8n instance on that machine:

npm install -g n8n-nodes-sitemap-validator

Then restart n8n. (Thanks to the n8n-community-node-package keyword in package.json, n8n picks it up automatically.)

🖐️ Manual install

If you want exact control over which version gets installed, or there's no UI option available:

Method 3 — Copy into the custom-nodes folder

Obtain the package (e.g. build it from the repo with npm pack ., or download it from npm), then place it in n8n's standard custom-nodes folder:

mkdir -p ~/.n8n/nodes
cp -R ./n8n-nodes-sitemap-validator ~/.n8n/nodes/

And restart n8n.

Method 4 — Upload the package in n8n

Package it as an archive file (npm pack . → .tgz), then:

1. Go to Settings → Community Nodes.
2. Click Install and choose Upload package.
3. Select the archive, install it, and restart n8n.

✅ For the npm route, the n8n-community-node-package keyword and the n8n block in package.json are already in place — just like official n8n community nodes.

🧭 Usage in a workflow

Connect the node to any trigger and tell it what to check. The Input Format dropdown decides how the Sitemap URL / XML / URLs field is read — including from incoming data via an expression, e.g. ={{ $json.sitemapUrl }}:

💡 Tip: point it at a live sitemap index (e.g. https://example.com/sitemap.xml) that links to sub-sitemaps — the node follows the whole tree and validates every URL across all of them.

⚙️ Filtering the output

The output fields (statusCode, status, isValid, issues, …) are fully filterable by n8n's built-in Filter node, but you can also filter inside this node with the Options → Only Show … settings. For example:

• Only healthy pages → Only Show Status Codes: 200
• Only what broke → Only Show URLs with Issues: on
• Only redirects & server errors → Only Show Status: redirect, server_error

The report/summary on every item always reflects the whole run, before filtering.

📊 Excel report

Turn Attach Excel Report on and the first output item carries a real .xlsx file as binary.data — no external library involved. The sheet ships with a frozen header row and column filters, so you can filter the report right inside Excel. Download it with a Write Binary File to Disk node, or email it with the Email / Send Email nodes:

Sitemap Validator ──► Write Binary File to Disk   (binaryPropertyName: data, fileName: sitemap-report.xlsx)

📤 Output

The node emits one item per URL, each carrying the full validation result plus the sitemap-wide summary:

{
  "url": "https://example.com/page",
  "lastmod": "2024-01-01",
  "hasLastmod": true,
  "statusCode": 200,
  "finalUrl": "https://example.com/page",
  "redirectCount": 0,
  "redirectChain": [],
  "error": null,
  "issues": [],
  "isValid": true,
  "status": "ok",
  "summary": {
    "sitemapUrl": "https://example.com/sitemap.xml",
    "inputFormat": "url",
    "totalUrls": 50,
    "checkedUrls": 50,
    "valid": 40,
    "validCount": 40,
    "issueCount": 10,
    "successRate": 80,
    "limited": false,
    "limit": null,
    "statusCodes": { "200": 39, "301": 5, "404": 3, "500": 1, "timeout": 2 },
    "issues": {
      "broken_link_404": 2,
      "client_error_4xx": 0,
      "server_error_5xx": 1,
      "redirect": 3,
      "redirect_loop": 0,
      "max_redirects": 0,
      "timeout": 1,
      "missing_lastmod": 2,
      "network_error": 0
    },
    "hasErrors": true,
    "durationMs": 12345
  }
}

The summary doubles as the final analysis report: successRate, validCount vs issueCount, the statusCodes histogram, the per-issue issues breakdown, and how long the run took (durationMs). When Max URLs to Check trimmed the run, limited is true and limit holds the number that was checked — the summary then reflects only what was actually validated.

status values

ok · broken · client_error · server_error · redirect · timeout · missing_lastmod · error · redirect_loop · max_redirects

issues (a URL can carry several)

broken_link_404 · client_error_4xx · server_error_5xx · redirect · redirect_loop · max_redirects · timeout · missing_lastmod · network_error

Handy expressions for downstream nodes

• Only broken links: ={{ $json.issues.includes('broken_link_404') }}
• Everything unhealthy: ={{ !$json.isValid }}
• Abort the run if anything is wrong: ={{ $json.summary.hasErrors }}

🧪 Testing

npm test

Spins up a local HTTP fixture server, loads a nested sitemap index + a gzip sitemap, and asserts that every issue type is detected — including redirect loops and redirect chains that exceed the hop limit.

🔧 Development

npm run build          # compile TypeScript once
npm run build:watch    # recompile continuously while you hack
npm run lint           # type-check only (no output files written)
npm test               # build + integration tests + node smoke test

Architecture notes:

• Manual redirect handling (redirect: 'manual') instead of auto-following — so the entire chain is recorded and loops are detectable.
• AbortSignal.timeout() per request for precise timeout detection.
• Fixed-size worker pool (mapWithConcurrency) keeps parallel requests under control and preserves input order.
• Gzip detected by magic bytes (0x1f 0x8b), so it works even without a Content-Encoding header.

🤝 Contributing

Found a bug, or have an idea? Feel free to open an issue or a pull request. Keep it small, test it, and make sure npm test passes.

📄 License

MIT © Mehrdad Ashtari

💼 Need a custom n8n workflow?

Need a custom n8n workflow?
Get professional n8n development & automation support at

https://tally.so/r/q4q1L9