Home General Troubleshooting

Troubleshooting

Last updated on Aug 12, 2026

Troubleshooting Guide

This guide helps you solve common issues with the Itinerator WordPress plugin.

Quick Diagnosis

Check API Keys

  1. Verify Platform API Key is valid
  2. Test DMO API Key (if using DMO content)
  3. Check Google Maps API Key (if using maps)

Common Issues

No Content Displaying

Symptoms:

  • Blocks show "No content to display"
  • Empty pages with no error messages
  • "Loading..." messages that never complete

Solutions:

  1. Check API keys in Itinerator → Settings
  2. Verify content exists in your Tourismo admin
  3. Clear caching plugins (W3 Total Cache, WP Rocket, etc.)
  4. Clear Itinerator Cache (From Admin bar or plugin Settings screen.)
  5. Check browser console for JavaScript errors
  6. Test with a simple block first

Debugging Steps:

# Check if API is responding
curl -H "Authorization: Bearer YOUR_API_KEY" https://admin.itinerator.ca/api/wp/v1/itineraries

Blocks Not Appearing

Symptoms:

  • No Itinerator blocks in block inserter
  • "Itinerator" not found in block search
  • Missing block categories

Solutions:

  1. Verify plugin activation in Plugins → Installed Plugins
  2. Check WordPress version (requires 5.0+)
  3. Ensure you're using block editor (not classic editor)
  4. Clear browser cache and refresh
  5. Check for JavaScript errors in browser console

Debugging Steps:

  • Try a different browser
  • Check API key is valid, resave the plugin settings page.
  • Disable other plugins temporarily
  • Check if theme supports Gutenberg

Layout Issues

Symptoms:

  • Blocks not aligned properly
  • Responsive design not working
  • CSS conflicts with theme

Solutions:

  1. Check Bootstrap compatibility - Plugin uses Bootstrap 4.6.1
  2. Test different column settings (1-4 columns)
  3. Try different alignment options
  4. Add custom CSS classes for styling
  5. Check theme CSS conflicts

Performance Problems

Symptoms:

  • Slow page loading
  • High server resource usage
  • Timeout errors

Solutions:

  1. Use page whitelist in settings to limit script loading
  2. Enable Itinerator caching (From plugin Settings page)
  3. Reduce number of blocks per page
  4. Optimize images in your Tourismo admin
  5. Use appropriate cache settings

Performance Tips:

  • Limit to 5-10 blocks per page

Google Maps Not Working

Symptoms:

  • Maps not displaying
  • "Google Maps API error" messages
  • Blank map areas
  • Map shows "No locations found" on a Single Guide page

Solutions:

  1. Verify Google Maps API key in settings
  2. Check API key restrictions (domain, IP)
  3. Enable Maps JavaScript API in Google Cloud Console
  4. Set up billing in Google Cloud Console
  5. Check API quota and usage limits
  6. Guide maps: Enable Show Record Boundaries — many guides have a geofence but no center lat/lng. Clear Itinerator cache after changing map settings.

Guide Filtering Looks Wrong

Symptoms:

  • Listings/events/itineraries missing on a Single Guide page
  • Expecting parent-region results (e.g. a brewery outside the guide polygon)

Solutions:

  1. Confirm the guide and the records share tags — guide membership is bounds + shared tags, not parent-region geography
  2. On Single Guide pages, hierarchy modes (children/parents/lineage) are not available for collection blocks; use Use current guide (automatic) or pick a specific region/guide manually
  3. See Guides and Listings for details

Guides Upgrade / 404s After API Split

Symptoms:

  • Single page for a guide returns 404 or empty content after upgrading
  • Related Posts no longer match posts that used to be tagged with a guide
  • Guides disappeared from a Regions collection (expected — they now use the Guides block)

Solutions:

  1. Deploy plugin + API together, then clear Itinerator cache
  2. Set Page Type to Single Guide for individual guide templates (not Region)
  3. Re-tag Related Posts under Itinerator Guides (itin-guides) if they used guide IDs on itin-regions
  4. Add a Guides block where you want guides listed — Regions only returns destination regions
  5. Full checklist: Upgrading to Guides

API Key Setup:

  1. Go to Google Cloud Console
  2. Create or select a project
  3. Enable Maps JavaScript API
  4. Create credentials (API key)
  5. Restrict key to your domain
  6. Add key to plugin settings

Shortcode Issues

Symptoms:

  • Shortcodes not rendering
  • "Shortcode not found" errors
  • Shortcodes showing as text

Solutions:

  1. Verify shortcode syntax (check brackets and quotes)
  2. Check if plugin is activated
  3. Clear page builder caches
  4. Test shortcode in classic editor
  5. Copy shortcode from block settings
  6. Verify that each shortcode has required attributes, see block description

Common Shortcode Mistakes:

# Wrong - missing quotes
[tourismo-itineraries show_title=true]

# Correct - with quotes
[tourismo-itineraries show_title="true"]

# Wrong - extra spaces
[tourismo-itineraries show_title = "true"]

# Correct - no extra spaces
[tourismo-itineraries show_title="true"]

# Wrong - Form block tag (not registered)
[tourismo-form selected_form="123"]

# Correct - Form block uses block type form-block
[tourismo-form-block selected_form="123"]

# Wrong - Featured Listings tag
[tourismo-listings-featured linked_page_id="123"]

# Correct - Featured Listings block type is featured
[tourismo-featured linked_page_id="123"]

Theme Compatibility

Symptoms:

  • Blocks not styling properly
  • Layout conflicts with theme
  • Missing Bootstrap styles

Solutions:

  1. Use custom CSS classes for styling
  2. Test with default WordPress theme
  3. Contact theme developer for compatibility

Advanced Troubleshooting

Debug Mode

Enable WordPress debug mode to see detailed error messages:

// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Check Error Logs

WordPress Debug Log:

  • Location: /wp-content/debug.log
  • Check for PHP errors and warnings

Server Error Logs:

  • Apache: /var/log/apache2/error.log
  • Nginx: /var/log/nginx/error.log
  • Check for server-level issues

API Testing

Test API connectivity directly:

# Test Platform API
curl -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
     https://admin.tourismo.co/api/wp/v1/itineraries

# Test DMO API (if applicable)
curl -H "Authorization: Bearer YOUR_DMO_API_KEY" \
     https://admin.tourismo.co/api/wp/v1/dmos

Browser Developer Tools

  1. Open Developer Tools (F12)
  2. Check Console for JavaScript errors
  3. Check Network tab for failed requests
  4. Check Elements tab for CSS issues

Getting Help

Before Contacting Support

  1. Document the issue:

    • Screenshots of the problem
    • Error messages (exact text)
    • Steps to reproduce
    • Browser and device information

  2. Gather system information:

    • WordPress version
    • Plugin version
    • Theme name and version
    • PHP version
    • Server environment

  3. Test basic functionality:

    • Try with default WordPress theme
    • Disable other plugins temporarily
    • Test in different browser
    • Check on mobile device

Contact Information

Itinerator Support:

  • Email: support@itinerator.ca
  • Website: https://support.tourismo.co
  • Include detailed issue description

WordPress Support:

  • For general WordPress issues
  • WordPress.org support forums

Prevention Tips

Regular Maintenance

  • Keep WordPress updated
  • Update plugins regularly
  • Backup your site before major changes
  • Monitor error logs

Best Practices

  • Test changes on staging site first
  • Use appropriate caching settings
  • Optimize images before uploading
  • Monitor performance regularly

Documentation

  • Keep notes of customizations
  • Document API keys and settings
  • Save working configurations
  • Track changes over time

Still having issues? Contact Itinerator support with detailed information about your problem.