BugWP logo BugWP
Back to Community
Home / Community / Plugin → Easy table of contents

Troubleshooting Common Easy Table of Contents Plugin Conflicts

32 threads Sep 16, 2025 Plugin → Easy table of contents

Content

Users of the Easy Table of Contents plugin occasionally encounter issues where the plugin doesn't function as expected. Based on community reports, many of these problems stem from conflicts with other plugins, themes, or server configurations. This guide outlines the most common issues and their solutions.

Common Issues and Solutions

1. Plugin or Page Crashes (White Screen of Death)

Problem: Activating the plugin causes a white screen, a "service not available" error, or pages fail to load entirely (e.g., ERR_HTTP2_PROTOCOL_ERROR).

Why it happens: This is often caused by a fatal PHP error triggered by a conflict with your theme or another plugin. It can also be related to server timeouts or resource limits.

Solution:

  • Check your server's PHP error logs. These logs will contain the specific error message causing the crash, which is the key to diagnosing the problem.
  • Perform a conflict test. Deactivate all other plugins and switch to a default WordPress theme (like Twenty Twenty-Four). If the issue resolves, reactivate your plugins and theme one by one to identify the culprit.
  • Ensure your PHP version (7.4 or higher) and WordPress installation are up to date.

2. Table of Contents Not Appearing

Problem: The table of contents box does not show up on posts or pages.

Why it happens: The most common reason is that the post or page does not meet the minimum number of headings required for the TOC to auto-insert. Other causes include the plugin's CSS being disabled or specific settings that exclude the content type.

Solution:

  • Ensure your post contains enough headings (H2, H3, etc.). The default minimum is 4.
  • Verify that the "Enable support" checkbox for your specific post type (e.g., posts, pages) is checked in the plugin's settings.
  • Check that you haven't disabled the plugin's CSS in the Advanced settings.
  • If using a page builder, you may need to insert the [toc] shortcode manually into your page content.
  • For the homepage, you must explicitly enable the "Homepage" option in the Advanced settings section.

3. JavaScript Features Not Working (Collapse/Expand, Smooth Scrolling)

Problem: The collapse/expand toggle or smooth scrolling when clicking a TOC link does not work. Clicking a link may just jump to the top of the page.

Why it happens: This is almost always due to conflicts with optimization plugins that minify or combine JavaScript files (e.g., WP Rocket, Autoptimize). The process can break the plugin's scripts.

Solution:

  • In your optimization plugin's settings, exclude the following Easy Table of Contents files from minification and concatenation:
    • /easy-table-of-contents/ (exclude the entire plugin directory)
    • Or specifically: js/eztoc.js, js/smooth-scroll.min.js
  • Clear all your caching layers (plugin, server, browser) after making these changes.

4. AMP Validation Errors

Problem: The official AMP for WordPress plugin reports validation errors caused by Easy Table of Contents.

Why it happens: The plugin may inject CSS or JavaScript that is not compliant with AMP's strict standards.

Solution:

  • This typically requires compatibility updates from the Easy Table of Contents development team. Monitor the plugin's update log for AMP-related fixes.
  • As a temporary workaround, you may need to disable the TOC on AMP versions of your pages if the option exists within your AMP plugin.

5. Styling and Display Issues

Problem: The TOC appears but has visual problems, such as misaligned text in RTL languages or a broken toggle button.

Why it happens: These issues are usually due to CSS conflicts with your theme.

Solution:

  • Use custom CSS to override the conflicting styles. You can add custom CSS in the WordPress Customizer under "Additional CSS." For example, for RTL alignment, the plugin's author has suggested: 
    div#ez-toc-container p.ez-toc-title {
    text-align: right;
    width: 100%;
}

General Troubleshooting Steps

If you encounter an issue not listed above, follow these steps:

  1. Conflict Test: Deactivate all other plugins and switch to a default theme. If the problem goes away, reactivate them one by one to find the conflict.
  2. Check Settings: Double-check all relevant settings in the Easy Table of Contents configuration pages.
  3. Clear Cache: Clear any page, browser, or server caches that might be serving an old version of your page.

By methodically working through these common problems, you can usually resolve issues and get your table of contents functioning smoothly.

Related Support Threads Support