Troubleshooting

Troubleshooting

Site Shows Fatal Error After Activation

  1. Check PHP version: php -v → must be 8.2+
  2. Check the cybermaps_fatal_errors option in the database for logged errors
  3. Verify cybermaps.php entry point is not corrupted
  4. Check file permissions on src/ directory

Static Files Not Being Served

  1. Verify files exist on disk: ls -la /path/to/wordpress/llms.txt
  2. Check web server configuration: Nginx or Apache must serve the file directly
  3. Check cybermaps_static_write_errors option for write failures
  4. Verify directory permissions on ABSPATH

Discovery Endpoints Return 404

  1. Flush rewrite rules: Settings → Permalinks → Save Changes (or wp rewrite flush)
  2. Verify Discovery Hub is enabled in Settings → Discovery
  3. Check that no other plugin is intercepting the same paths
  4. Try disabling the Static File Engine and test dynamic responses first

Sitemap Shows No URLs

  1. Verify post types are selected in Settings → Sitemaps
  2. Check exclusion settings: excluded post IDs, categories, or tags
  3. Check that posts are published (not draft, pending, or private)
  4. Clear sitemap cache via WP-CLI: wp cybermaps clear_cache

Logs Table Is Empty

  1. Verify analytics are enabled in Settings → Logs
  2. Check that bot traffic is actually hitting discovery endpoints
  3. Check the CrawlerRegistry: the visiting bot must match a known User-Agent
  4. Verify the logs table exists: SHOW TABLES LIKE '%cybermaps_logs%'

Settings Changes Not Taking Effect

  1. Clear any persistent object cache (memcached, Redis)
  2. Disable and re-enable the Static File Engine to force regeneration
  3. Regenerate static files manually: wp cybermaps regenerate
  4. Check for plugin conflicts: another plugin may be hooking into the same options

Memory Exhaustion Errors

  1. Increase PHP memory limit: define('WP_MEMORY_LIMIT', '256M');
  2. Disable RAG chunk generation if not needed
  3. Reduce the max_urls_per_chunk setting for very large sites
  4. Consider offloading static file sync to WP-CLI instead of background processes

Plugin Check Warnings

The plugin uses phpcs:ignore comments for intentional deviations:

  • WordPress.DB.DirectDatabaseQuery: logs table uses $wpdb directly (by design)
  • WordPress.DB.PreparedSQL.InterpolatedNotPrepared: table names in SQL (by design, $wpdb->prefix is safe)
  • WordPress.Security.EscapeOutput.OutputNotEscaped: discovery endpoint content (integrity-checked, by design)

These are documented exceptions, not oversights.

Getting Help

  • Plugin homepage: https://cybermaps.dev
  • Bug reports: Include PHP version, WordPress version, and the cybermaps_fatal_errors option contents
  • Feature requests: Include the use case and expected behavior