Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Troubleshooting

WordPress Do_shortcode Not Working: Causes and How to Fix It

WordPress Do_shortcode Not Working: Causes and How to Fix It

Short answer

do_shortcode usually fails because its result is not echoed, the shortcode is not registered yet when you call it, the tag has a typo or curly quotes, or the shortcode callback echoes instead of returning output. Echo the result, call it after init and check that shortcode_exists returns true.

Key takeaways

  • do_shortcode returns a string, so echo it in templates.
  • Raw shortcode text on the page means the tag was not registered at that moment.
  • Shortcode callbacks must return output, not echo it.
  • Custom fields, titles and menus need do_shortcode applied manually.
  • Escaping the final output can turn shortcode HTML into visible text.

Why is do_shortcode not working in WordPress?

do_shortcode usually fails because the shortcode is not registered when you call it, the result is never echoed, the tag is misspelled, or the shortcode's own callback echoes instead of returning output.

The function itself is simple. It takes a string, finds registered shortcode tags inside it and replaces them with their output. If nothing is registered under that tag at that moment, WordPress leaves the text untouched.

That is the key clue. If you see the raw [shortcode] text on the page, WordPress did not recognize the tag. If you see nothing at all, the shortcode ran but its output went nowhere.

The do_shortcode function reference describes exactly what it does. The sections below cover each common cause and its fix.

If you are new to shortcodes, our explainer on what a shortcode is in WordPress covers the basics.

Are you echoing the result of do_shortcode?

do_shortcode returns a string and does not print anything, so you must echo it in a template file or nothing appears.

This is the most common mistake in theme files. This does nothing visible:

<?php do_shortcode( '[contact-form-7 id="123"]' ); ?>

This works:

<?php echo do_shortcode( '[contact-form-7 id="123"]' ); ?>

Inside a function that builds HTML, add the result to your output string instead of echoing it directly. Mixing the two causes content to appear in the wrong place.

Is the shortcode registered when you call it?

If the plugin or code that registers the shortcode has not run yet, or does not run on that page, do_shortcode cannot find the tag and returns the text unchanged.

Shortcodes are registered with add_shortcode, usually on the init hook. If you call do_shortcode before init, or in a file that loads early, the tag does not exist yet.

Common examples include:

  • Calling do_shortcode directly in a plugin's main file, outside any hook.
  • Using a shortcode from a plugin that only registers it on the front end, then calling it in the admin or a REST request.
  • Calling it in an AJAX handler where the plugin skips registration.
  • The plugin providing the shortcode is deactivated.

Check whether the tag exists with shortcode_exists:

if ( shortcode_exists( 'my_shortcode' ) ) {
    echo do_shortcode( '[my_shortcode]' );
}

If it returns false, move your call to a later hook such as wp or template_redirect, or render it inside the template. Our guide to WordPress hooks explains the load order.

Is the shortcode syntax correct?

A typo in the tag name, curly quotes, missing brackets or a wrong attribute name will stop the shortcode from rendering correctly.

Check these details:

  • Tag name. It must match the registered name exactly, including dashes or underscores.
  • Quotes. Use straight quotes. Curly quotes copied from a document or a website break attributes.
  • Brackets. Every shortcode needs square brackets. Enclosing shortcodes need a closing tag such as [/box].
  • Attributes. Use the names the shortcode expects. Unknown attributes are ignored.

PHP quoting can trip you up too. If your shortcode uses double quotes for attributes, wrap the whole string in single quotes, or escape the inner quotes.

The Shortcode API documentation lists the syntax rules. Our guide on how to write a shortcode in WordPress shows correct patterns with examples.

Does the shortcode callback echo instead of return?

A shortcode callback must return its output, because echoing makes the content print at the top of the page or in the wrong spot.

If you wrote the shortcode yourself, look at its function. This is wrong:

function my_box() {
    echo '<div class="box">Hello</div>';
}

This is right:

function my_box() {
    return '<div class="box">Hello</div>';
}

If the callback needs to include a template file that echoes HTML, wrap it in output buffering with ob_start and ob_get_clean, then return the buffered string. PHP documents this in its output control functions.

Why does a shortcode not work in widgets, titles or custom fields?

WordPress only runs shortcodes automatically in post content and a few widgets, so text in titles, custom fields, menus or excerpts needs do_shortcode applied manually.

Post content goes through a filter that processes shortcodes. Many other places do not. A shortcode typed into a custom field, an Advanced Custom Fields value or a menu label stays as plain text.

To fix it, pass that value through do_shortcode when you output it:

echo do_shortcode( get_post_meta( get_the_ID(), 'promo_text', true ) );

For excerpts and titles, you can add a filter, but be careful. Running shortcodes in titles can affect SEO plugins and admin screens. Only process the fields you control.

In the block editor, use the Shortcode block rather than a paragraph block for the most reliable result.

Is something escaping or stripping the output?

Escaping functions such as esc_html can turn shortcode HTML into visible text, and some sanitizers strip shortcode output entirely.

If you see HTML tags printed as text on the page, an escaping function is running after do_shortcode. For example, wrapping the result in esc_html converts tags into plain characters.

Fixes include:

  • Escape the shortcode's attributes inside the callback, not the final output.
  • Use wp_kses_post if you need to allow safe HTML.
  • Check your theme for filters that strip tags from that area.

Also check the reverse. If a plugin calls strip_shortcodes on the content, the shortcode is removed before it can run.

What does each symptom usually mean?

Match what you see on the page to the most likely cause.

What you seeLikely causeFix
Raw [shortcode] textTag not registered at that pointCheck shortcode_exists, call later
Nothing at allResult not echoedAdd echo before do_shortcode
Output at top of pageCallback echoesReturn the output instead
HTML shown as textOutput escaped afterwardsUse wp_kses_post or no escaping
Works in posts, not fieldsField not filteredWrap the field in do_shortcode
Works for admins onlyCaching or role checkClear cache, check callback logic

Could a plugin conflict or caching be the cause?

Yes, a conflicting plugin can unregister or override a shortcode, and page caching can keep showing an old broken version after you fix it.

Two plugins sometimes register the same tag. The one that loads last wins, so you may get the wrong output. Search your plugins for the tag name to find duplicates.

To isolate the problem, run a conflict test on a staging copy. Our guide to fixing a plugin conflict walks through it.

Clear page caches after each fix. Otherwise visitors may keep seeing the old result. Our guide on how to clear cache in WordPress covers each layer.

How do you debug do_shortcode step by step?

Turn on debugging, confirm the shortcode exists, test it with a hard-coded string, then add your real content back one piece at a time.

  1. Enable WP_DEBUG and logging. Our guide on enabling debug mode in WordPress shows how.
  2. Check shortcode_exists for your tag at the point you call it.
  3. Echo do_shortcode with a simple, known-good shortcode such as [gallery].
  4. Swap in your shortcode with no attributes.
  5. Add attributes back one at a time.
  6. Check the debug log for warnings from the callback.

This narrows the problem to registration, syntax or the callback itself in a few minutes.

If the shortcode comes from a plugin you did not write, check that plugin's documentation and support forum. Many plugins list where their shortcodes work and any settings that limit them to certain pages.

Frequently asked questions

What does do_shortcode return if the shortcode does not exist?

It returns the original text unchanged. So if the tag is not registered, you see the raw square-bracket text on the page. Use shortcode_exists to check whether the tag is registered before calling do_shortcode.

Can I use do_shortcode in functions.php?

Yes, but only inside a function that runs on a hook after the shortcode is registered, or inside a template. Calling it directly at the top level of functions.php runs too early for most plugin shortcodes, so it returns the raw text.

Why does my shortcode output appear at the top of the page?

The shortcode callback is echoing its HTML instead of returning it. WordPress prints echoed output immediately, before the rest of the content is placed. Change the callback to return a string, using output buffering if it includes a template.

Do shortcodes work in block themes?

Yes. Use the Shortcode block in posts, pages or templates in the Site Editor. In theme PHP files, which block themes rarely use, call do_shortcode and echo the result as you would in a classic theme.

Is do_shortcode slow?

It is fast for normal use, but each shortcode runs its own callback, and some run database queries or remote requests. If a page with many shortcodes is slow, profile the callbacks rather than do_shortcode itself.

Sources

  1. do_shortcode() WordPress Developer Resources
  2. add_shortcode() WordPress Developer Resources
  3. Shortcodes Plugin Handbook
  4. ob_start PHP Manual

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.