Issues Fixes

Common issues and their solutions when working with Strapi Advanced Sitemap.

Common Issues

Sitemap returns 401 Unauthorized

Cause: The requesting role doesn’t have permission to access the sitemap endpoint.

Solution:

• Go to Settings → Users & Permissions → Roles
• Select the role (typically Public for search engines)
• Enable the corresponding plugin action:
  • serveRootSitemap for /sitemap.xml
  • serveManualSitemapIndex for /sitemaps/manual-sitemaps
  • serveManualSitemapFile for /sitemaps/{filename}.xml
  • serveCollectionSitemapFile for collection sitemaps
• Click Save

Manual sitemap URL returns 404

Cause: The sitemap file doesn’t exist or the filename/path is incorrect.

Solution:

• Verify the filename matches exactly (case-sensitive)
• Check the base path configuration
• Ensure you clicked “Save changes” after creating/editing the sitemap
• Verify the sitemap is enabled in the admin panel
• Check that the URL pattern matches: /sitemaps/{filename}.xml

Collection sitemap is empty

Cause: No published entries match the pattern, or the pattern has unresolved tokens.

Solution:

• Verify entries are published (if Draft & Publish is enabled)
• Check that the URL pattern resolves correctly:
  • All tokens (e.g., [slug]) must match existing fields
  • Nested fields (e.g., [author.slug]) must exist
  • No leftover tokens should remain in the final URL
• Test the pattern with a sample entry
• Check that the collection type has entries

Admin UI appears stale or outdated

Cause: The admin panel hasn’t been rebuilt after plugin installation or update.

Solution:

• Stop Strapi if it’s running
• Run npm run build to rebuild the admin panel
• Restart Strapi with npm run develop
• Clear your browser cache if the issue persists

URLs in sitemap are incorrect

Cause: Base URL configuration is missing or incorrect.

Solution:

• Go to Settings → Strapi Advanced Sitemap
• Set the Frontend Base URL to your production domain
• Verify relative paths resolve correctly using the preview feature
• Check that manual sitemap entries use correct paths

Collection sitemap pattern doesn’t resolve

Cause: Field names in the pattern don’t match the collection schema.

Solution:

• Verify field names are correct (case-sensitive)
• For nested fields, ensure the relation exists and the field is accessible
• Test with a simple pattern first (e.g., [slug])
• Check the collection type schema in Content-Type Builder

Sitemap not appearing in root index

Cause: Sitemap configuration may not be saved or enabled.

Solution:

• Ensure the sitemap is saved (click “Save changes”)
• Verify the sitemap is enabled in the admin panel
• Check that permissions are granted for the root sitemap endpoint
• Clear any caching that might be affecting the response

Debugging Tips

• Check browser console: Look for JavaScript errors in the admin panel
• Verify Strapi logs: Check server logs for errors or warnings
• Test endpoints directly: Use curl or a browser to test sitemap URLs
• Validate XML: Use an XML validator to ensure sitemap format is correct
• Check permissions: Verify role permissions are saved correctly
• Review configuration: Double-check all settings in the admin panel

Getting Help

If you’re still experiencing issues:

• Check the GitHub repository for known issues
• Review the Technical API Guide for endpoint details
• Verify your Strapi version is compatible (5.x required)
• Ensure Node.js version meets requirements (>= 18.0.0)

Prevention Checklist

To avoid common issues:

• Always click “Save changes” after editing sitemaps
• Set the frontend base URL before creating sitemaps
• Grant permissions to the Public role for search engine access
• Test URL patterns with sample entries before deploying
• Rebuild admin panel after plugin installation/updates
• Verify published status of entries for collection sitemaps
• Use the preview feature to verify URLs resolve correctly