PHP Sitemap Generator: Fixing the 1,000 Sitemap Files Limit Error

The error occurs when SunSitemap::createSitemap() generates more than 1,000 XML files, which happens when your total URL count divided by the $maxUrl chunk size exceeds 1,000.

The msbatal/php-sitemap-generator library enforces a strict ceiling on the number of sitemap files per directory to comply with search engine indexing standards. When you add URLs via addUrl() and call createSitemap(), the class splits your URL list into chunks and validates the total file count before writing to disk. Understanding this limit prevents runtime exceptions in large-scale sitemap generation.

What Triggers the 1,000 Sitemap Files Error?

Inside SunSitemap.php, the createSitemap() method processes your URL collection using PHP’s array_chunk() function. It divides $this->urls into segments based on the $maxUrl property (defaulting to 50,000 URLs per file) and stores each segment in the $this->sitemaps array.

Immediately after chunking, the code performs a hard count validation at lines 1414–1415:

if (sizeof($this->sitemaps) > 1000) {
    throw new Exception(
        "The sitemap directory (index) can contain a maximum of 1,000 sitemap files."
    );
}

If sizeof($this->sitemaps) exceeds 1,000, the library aborts execution and throws the exception rather than risk creating an invalid sitemap index structure.

Common Causes of Exceeding the Limit

Three specific scenarios push the sitemap file count over the threshold:

• Massive URL volumes: With the default 50,000 URL limit per file, you need more than 50 million URLs to hit the ceiling. However, reducing $maxUrl lowers this threshold proportionally.
• Reduced chunk sizes: Setting $maxUrl to 10,000 or lower (for memory optimization) causes the same URL set to generate 5× more files, quickly approaching the 1,000-file cap on large sites.
• Accumulated instances: Reusing the same SunSitemap object across multiple generation cycles in long-running scripts accumulates files in $this->sitemaps without resetting the counter between jobs.

Reproducing and Fixing the Error

Code Example: Staying Under the Limit

The following script generates 250,000 URLs with the default 50,000 URL-per-file setting, resulting in only 5 files:

<?php
require 'SunSitemap.php';

$sm = new SunSitemap('https://example.com', 'sitemaps/');
for ($i = 1; $i <= 250000; $i++) {
    $sm->addUrl("page{$i}.html");
}
$sm->createSitemap()->updateRobots();
?>

Code Example: Triggering the Exception

This demonstration forces a low $maxUrl value of 100 to quickly exceed the limit with 105,000 URLs:

<?php
require 'SunSitemap.php';

$sm = new SunSitemap('https://example.com', 'sitemaps/', 100);

for ($i = 1; $i <= 105000; $i++) {
    $sm->addUrl("page{$i}.html");
}

try {
    $sm->createSitemap();
} catch (Exception $e) {
    echo $e->getMessage(); 
    // Output: "The sitemap directory (index) can contain a maximum of 1,000 sitemap files."
}
?>

Solutions: Increasing Chunk Size or Batching

Resolve the error by either increasing the chunk size to reduce file count, or instantiating fresh SunSitemap objects for logical batches:

Option 1: Raise the URL limit per file

$sm = new SunSitemap('https://example.com', 'sitemaps/', 50000);

Option 2: Process in isolated batches

$batchSize = 5000000; // 5M URLs = 100 files at 50k per file
for ($batch = 0; $batch < $totalUrls; $batch += $batchSize) {
    $sm = new SunSitemap('https://example.com', "sitemaps/batch{$batch}/");
    // Add URLs for this specific batch...
    $sm->createSitemap()->updateRobots();
}

Summary

• The 1,000 sitemap file limit is hardcoded in SunSitemap.php at lines 1414–1415 as a safeguard against invalid index structures.
• The error triggers when sizeof($this->sitemaps) exceeds 1,000 during the array_chunk() operation inside createSitemap().
• Default behavior allows up to 50 million URLs (1,000 files × 50,000 URLs), but lowering $maxUrl reduces this capacity.
• Reusing instances without resetting state causes cumulative file counts across multiple generation jobs.
• Fixes include increasing $maxUrl, implementing batch processing with fresh instances, or splitting content across multiple directory indexes.

Frequently Asked Questions

What is the maximum number of URLs the PHP Sitemap Generator can handle?

With default settings, the library supports 50 million URLs (1,000 files × 50,000 URLs per file). However, you can handle larger datasets by splitting the workload across multiple SunSitemap instances writing to different directories, effectively creating separate sitemap indexes.

How do I check how many sitemap files will be generated before calling createSitemap?

Calculate the projected file count by dividing your total URL count by your $maxUrl value. If the result exceeds 1,000, either increase the $maxUrl parameter in the constructor or partition your URLs across multiple SunSitemap objects to stay under the SunSitemap.php limit enforced at lines 1414–1415.

Can I modify the 1,000 file limit in the source code?

While you could edit the hardcoded value in SunSitemap.php, this violates the sitemap index protocol recognized by major search engines. Google and Bing both enforce a 1,000-file limit per sitemap index for optimal crawling performance. Instead of raising the limit, implement a multi-index architecture using separate directories or partner with a CDN that supports dynamic sitemap generation.

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