How to Fix WordPress Shortcode Not Working

Shortcodes are one of WordPress’s most powerful features. They let you add dynamic content with just a small tag like [my-gallery] or [my-form]. But when a shortcode doesn’t work, it can be frustrating. Sometimes it just shows as plain text, or it doesn’t output anything at all.

Why Shortcodes Stop Working in WordPress

  • Incorrect shortcode syntax
  • Placing shortcodes in the wrong block (Gutenberg/Block Editor)
  • Plugin or theme conflicts
  • Shortcodes not enabled in widgets, excerpts, or menus
  • Auto-formatting (wpautop) breaking the markup
  • Caching issues (page cache, CDN, browser)
  • Deactivated plugin or missing shortcode function

How to Fix WordPress Shortcode Not Working

Follow these steps one by one until your shortcode works again.

1. Check Shortcode Syntax

Use the correct format:

[shortcode attribute="value"]
[shortcode]Content[/shortcode]

Always use straight quotes (") not curly quotes (" "). Close paired shortcodes properly.

2. Use the Shortcode Block in Gutenberg

Shortcodes don’t always work in a Paragraph or Code block. Use the Shortcode block instead:

  1. Click the + icon.
  2. Search for Shortcode.
  3. Paste your shortcode inside.

3. Enable Shortcodes in Widgets, Excerpts, and Other Fields

By default, WordPress doesn’t run shortcodes everywhere. Add these snippets to your child theme’s functions.php or a code snippets plugin:

// Enable shortcodes in widgets
add_filter('widget_text', 'do_shortcode');

// Enable shortcodes in excerpts
add_filter('the_excerpt', 'do_shortcode');

// Enable shortcodes in term/category descriptions
remove_filter('term_description', 'wpautop');
add_filter('term_description', 'do_shortcode');

// Enable shortcodes in WooCommerce product short description
add_filter('woocommerce_short_description', 'do_shortcode', 11);

4. Make Sure the Plugin or Theme is Active

Many shortcodes are created by plugins (e.g., Contact Form 7, WooCommerce). If the plugin is deactivated, the shortcode won’t work.

Go to Plugins → Installed Plugins and confirm the plugin is active.

5. Fix wpautop Formatting Issues

WordPress automatically adds <p> and <br> tags, which can break shortcodes.

Add this to your functions file:

add_filter('the_content', 'shortcode_unautop', 100);

6. Clear Cache

If you’re using a caching plugin (WP Rocket, W3 Total Cache, LiteSpeed) or a CDN (Cloudflare, Fastly), purge your cache after fixing shortcodes. Also clear your browser cache.

7. Test for Plugin or Theme Conflicts

  1. Switch to a default WordPress theme (e.g., Twenty Twenty-Five).
  2. Deactivate all plugins except the one providing the shortcode.
  3. If the shortcode works, reactivate plugins one by one until you find the conflict.

8. Debug Custom Shortcodes

If you created your own shortcode, ensure your function returns output (not echo).

Example:

function mybox_shortcode($atts, $content = '') {
    $atts = shortcode_atts(
        array('color' => 'blue'),
        $atts,
        'mybox'
    );
    return '<div class="mybox mybox-' . esc_attr($atts['color']) . '">' . do_shortcode($content) . '</div>';
}
add_shortcode('mybox', 'mybox_shortcode');

Common mistakes:

  • Using echo instead of return
  • Forgetting to allow nested shortcodes with do_shortcode($content)
  • Registering shortcodes inside functions that don’t run on the frontend

9. Run Shortcodes in PHP Templates

If you want to execute a shortcode directly in a template file:

echo do_shortcode('[mybox color="green"]Hello[/mybox]');

10. Clear Errors with Debug Mode

If you still can’t fix it, check for PHP errors by enabling debug mode in wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Then check the /wp-content/debug.log file for clues.

Leave a Comment