Troubleshooting

Troubleshooting

Time to read: 5 minutes

Solutions for common issues with Product Roadmap.

Display Issues

Roadmap Page is Blank

Check items exist:

  1. Go to Roadmap > All Items
  2. Ensure at least one item is published
  3. Verify item has a status assigned

Check shortcode:

  • Correct: [roadmap]
  • Ensure no extra spaces or typos
  • Try a simple shortcode first without parameters

Clear caches:

  • Deactivate caching plugins temporarily
  • Clear browser cache (Ctrl+Shift+R)
  • Check if a CDN is caching old content

Styles Look Broken

Theme conflicts:

  1. Switch to a default theme (Twenty Twenty-Four)
  2. If roadmap displays correctly, your theme has a CSS conflict
  3. Add custom CSS to resolve conflicts

JavaScript errors:

  1. Open browser console (F12 > Console tab)
  2. Look for red error messages
  3. Check if another plugin’s JS is failing

Missing assets:

  • Verify plugin files are complete
  • Try deactivating and reactivating the plugin
  • Re-upload the plugin if needed

Shortcode Shows as Text

Not rendering:

  • Ensure the plugin is activated
  • Check you’re using the correct shortcode: [roadmap]
  • Verify you’re in a page/post (not a widget that doesn’t support shortcodes)

Voting Issues

Votes Not Registering

Check settings:

  1. Go to Roadmap > Settings
  2. Ensure voting is enabled
  3. Check voting permissions (logged-in only vs. guests)

Cookie/session issues:

  • Clear browser cookies
  • Try in incognito/private mode
  • Check if a security plugin is blocking requests

AJAX errors:

  1. Open browser console (F12)
  2. Click the vote button
  3. Look for failed network requests
  4. Common cause: REST API blocked by security plugin

Duplicate Votes Allowed

Check permissions:

  • Guest voting uses cookies — clearing cookies allows re-voting
  • Logged-in voting is tracked per user and prevents duplicates
  • Consider restricting voting to logged-in users for accuracy

Item Management Issues

Can’t Add New Items

Check permissions:

  • Verify your WordPress user role has edit_posts capability
  • Administrators and Editors can add items by default
  • Check if a role management plugin has modified capabilities

Categories/Statuses Not Showing

Verify terms exist:

  1. Go to Roadmap > Statuses (or Categories)
  2. Ensure terms are created
  3. Check that items are assigned to them

Flush permalinks:

  1. Go to Settings > Permalinks
  2. Click Save Changes (no changes needed)
  3. This refreshes the rewrite rules

REST API Issues

API Endpoints Not Working

Check permalinks:

  • REST API requires pretty permalinks
  • Go to Settings > Permalinks
  • Select any option except “Plain”
  • Save changes

Security plugins:

  • Some security plugins block REST API access
  • Whitelist /wp-json/jesuspended-developer/ endpoints
  • Check plugin logs for blocked requests

CORS Errors

For external access:

  • REST API requests from other domains need CORS headers
  • Add appropriate headers in your theme’s functions.php or via a plugin
  • This only applies to cross-origin requests

Performance Issues

Roadmap Loads Slowly

Too many items:

  • Use the limit parameter: [roadmap limit="20"]
  • Filter by status to show fewer items
  • Enable pagination if available

Caching:

  • Install a caching plugin (WP Super Cache, W3 Total Cache)
  • Enable object caching if your host supports it
  • Consider a CDN for static assets

Admin Dashboard Slow

Large datasets:

  • Use filters to narrow down items in the admin list
  • Limit items per page in Screen Options
  • Check if other plugins are adding overhead

Plugin Conflicts

How to Diagnose

  1. Deactivate all other plugins (except Product Roadmap)
  2. Test the issue — if it’s resolved, a plugin conflict exists
  3. Reactivate plugins one by one until the issue returns
  4. The last activated plugin is causing the conflict

Common Conflicts

Caching plugins:

  • Exclude roadmap pages from caching
  • Clear cache after making changes

Security plugins:

  • Whitelist REST API endpoints
  • Check firewall rules for AJAX requests

Page builders:

  • Use the shortcode widget/module for page builders
  • Some builders need shortcode rendering enabled

Uninstallation

Clean Removal

  1. Deactivate the plugin first
  2. Delete through WordPress admin
  3. Plugin removes its options on deletion
  4. Roadmap items (custom post type) remain in database

Keeping Data

  • Roadmap items are stored as custom post types
  • They remain in the database after plugin removal
  • Reactivating the plugin restores access to all items

Getting Help

Before Contacting Support

  1. Update to the latest plugin version
  2. Check this troubleshooting guide
  3. Test with a default theme
  4. Disable other plugins to rule out conflicts

WordPress.org Support

  • Visit the support forum
  • Include your WordPress version, PHP version, and theme name
  • Describe steps to reproduce the issue

Pro Support

Last updated: March 4, 2026