Troubleshooting
WordPress Shortcode Not Working: Causes and How to Fix It

Short answer
A WordPress shortcode usually fails because the plugin or theme that registers it is inactive, the tag has typos or curly quotes, it sits in a Code block, or it is used where WordPress does not process shortcodes. Check the plugin, retype the tag in a Shortcode block, then clear caches.
Key takeaways
- Plain bracket text means no active code has registered that shortcode.
- Curly quotes and formatting inside the brackets break shortcodes.
- Use the Shortcode block, not the Code or Preformatted block.
- Theme template files need do_shortcode to run shortcodes.
- Custom shortcode functions must return output, not echo it.
- Clear every cache after fixing a shortcode.
Why is a WordPress shortcode not working?
A shortcode usually fails because the plugin or theme that registers it is inactive, it is typed with wrong characters or in the wrong block, or it sits somewhere WordPress does not process shortcodes.
A shortcode is a tag in square brackets, such as [contact-form-7 id=“12”], that WordPress swaps for real output when the page loads. If nothing registers that tag, WordPress leaves the text on the page exactly as you typed it.
The symptom tells you a lot.
Plain bracket text on the page points to a missing or misspelled shortcode. Output in the wrong spot points to code that echoes instead of returning. A blank space points to a PHP error or empty output.
New to shortcodes? Our explainer on what a shortcode is in WordPress covers the basics before you start fixing.
Is the plugin or theme that provides the shortcode active?
Check that the plugin or theme that created the shortcode is installed and active, because WordPress only replaces tags that some active code has registered.
This is the most common cause by far. It happens after you switch themes, deactivate a plugin, or copy content from another site.
- Theme shortcodes. Many older themes add their own shortcodes for buttons, columns and tabs. When you change themes, those tags stop working.
- Deactivated plugins. A form, slider or gallery plugin that was turned off leaves its tags behind.
- Pro features. Some shortcodes only work with the paid version of a plugin.
Go to Plugins > Installed Plugins and confirm the right plugin is active. If you changed themes, check the old theme's documentation to see whether its shortcodes moved to a companion plugin.
Is the shortcode typed correctly?
Make sure the name is spelled exactly, uses straight quotes around attribute values, and has no extra spaces, line breaks or formatting inside the brackets.
Copying shortcodes from emails, PDFs or word processors often swaps straight quotes for curly quotes. WordPress cannot read id=”12” with curly quotes, so it ignores the attribute.
Check these details:
- Exact name. Shortcode names are case-sensitive and must match exactly.
- Straight quotes. Retype the quotes on your keyboard inside the editor.
- No formatting. Bold or links inside the brackets break the tag.
- Closing tags. Enclosing shortcodes like [box]text[/box] need the closing tag with a forward slash.
- Correct IDs. A form or gallery ID that no longer exists can produce empty output.
The plugin's settings screen usually has a copy button for each shortcode. Use it rather than typing the tag by hand.
Are you adding the shortcode in the right block?
In the block editor, use the Shortcode block or a Paragraph block, and avoid the Code, Preformatted and Custom HTML blocks, which show the tag as text.
The Code and Preformatted blocks are built to display code, so they deliberately do not run shortcodes. The Shortcode block is the safest choice because WordPress outputs it without adding extra paragraph tags around it.
The WordPress Shortcode block documentation shows how to add it. Type /shortcode in the editor and paste the tag into the box.
In page builders, use the builder's own shortcode widget. Our guide on editing shortcodes in Elementor shows where it is in that builder.
Where does WordPress not run shortcodes?
WordPress does not run shortcodes everywhere by default; titles, excerpts, custom fields, menus and theme template files usually need extra code before shortcodes inside them work.
Shortcodes run in post and page content automatically. Widgets that use blocks generally process them too. Other places do not, including:
- Post and page titles.
- Manual excerpts, depending on the theme.
- Custom fields from plugins such as ACF, unless the field output is passed through shortcode processing.
- Navigation menu labels.
- Theme PHP template files.
To run a shortcode inside a PHP template, wrap it in do_shortcode():
<?php echo do_shortcode( '[my_shortcode]' ); ?>
The do_shortcode reference explains how it works. Only edit template files in a child theme, so an update does not wipe your changes.
Why does shortcode output appear in the wrong place?
Output appears at the top of the page or above the content when the shortcode function uses echo instead of returning its HTML as a string.
This is a common mistake in custom code. WordPress expects the shortcode callback to return its output. If it echoes, the HTML prints as soon as the function runs, which is before the content is shown.
Wrong:
function my_box() { echo '<div>Hello</div>'; }
Right:
function my_box() { return '<div>Hello</div>'; }
If the function includes a template file that echoes, wrap it with output buffering using PHP's ob_start function, then return the buffered content.
Why is a custom shortcode not working?
A custom shortcode fails when add_shortcode is never called, runs too late or only in admin, the name clashes with another shortcode, or the callback has a PHP error.
Check your code against these points:
- Registered on time. Call add_shortcode() directly in your plugin file or on the init hook.
- Not wrapped in is_admin(). Shortcodes render on the front end, so registering them only in admin means they never run for visitors.
- Unique name. Use a prefix like acme_button so you do not clash with another plugin.
- Code is loaded. Snippets added to an inactive theme or a disabled snippet plugin never run.
- No fatal error. Turn on debugging to see hidden PHP errors.
The add_shortcode reference shows the correct structure. For a full walkthrough, see our guide on how to write a shortcode in WordPress.
Why do nested shortcodes not work?
Nested shortcodes only work if the outer shortcode's function passes its content through do_shortcode, because WordPress does not process inner tags automatically.
For example, [tabs][tab]Text[/tab][/tabs] needs the tabs function to call do_shortcode( $content ) before returning. Without that, the inner tags show as plain text.
Also avoid using the same shortcode inside itself. WordPress's parser cannot reliably handle the same tag nested within its own opening and closing tags.
Can caching or a plugin conflict stop a shortcode from working?
Yes, a cached page can keep showing old output or plain tags, and a conflicting plugin or JavaScript error can stop interactive shortcodes like forms and sliders from working.
Clear your caching plugin, server cache and CDN after fixing a shortcode. Our guide on how to clear cache in WordPress covers each layer.
If the shortcode renders but does nothing when clicked, open the browser console and look for JavaScript errors. A script optimization setting that delays or combines files is a common cause.
To confirm a conflict, deactivate other plugins one at a time or use a troubleshooting mode plugin. See our guide to fixing a plugin conflict for the method.
What is the quickest way to diagnose a shortcode problem?
Match what you see on the page to the most likely cause, then work down the list from the simplest fix.
| What you see | Most likely cause | Fix |
|---|---|---|
| Tag shown as plain text | Plugin inactive or name wrong | Activate plugin, copy the exact tag |
| Tag shown in a code box | Placed in Code or Preformatted block | Move to Shortcode block |
| Output at top of page | Function echoes | Return the output instead |
| Nothing shown | PHP error or wrong ID | Enable debugging, check the ID |
| Inner tags shown as text | Nesting not supported | Use do_shortcode on content |
| Works in editor preview only | Cache | Clear all caches |
WooCommerce users have one extra case. Store pages built with blocks no longer use shortcodes like [woocommerce_cart], so mixing the two can leave a blank page. The WooCommerce shortcodes documentation lists what is still supported.
Frequently asked questions
Why is my shortcode showing as text on the page?
WordPress could not find a registered shortcode with that name. The plugin or theme that provides it may be inactive, the name may be misspelled, or the tag may be inside a Code block. Activate the plugin and paste the exact tag into a Shortcode block.
Do shortcodes work in WordPress widgets?
Yes, in current WordPress versions block-based widget areas process shortcodes, and the Shortcode block works in widgets too. Very old themes with classic widgets may need a plugin or a small filter to enable shortcodes in text widgets.
How do I use a shortcode in a theme template file?
Wrap the tag in the do_shortcode function and echo the result inside your PHP template. Make the edit in a child theme so theme updates do not remove it. For block themes, add a Shortcode block to the template in the Site Editor instead.
Why does my shortcode work in preview but not on the live page?
The live page is probably served from cache. Clear your caching plugin, any server cache and your CDN, then reload in a private window. If it still fails, check for script optimization settings that delay the shortcode's JavaScript.
Why did my shortcodes stop working after changing themes?
Your old theme likely registered those shortcodes. When you switch themes, its shortcodes are no longer available. Install a plugin that provides the same shortcodes, reactivate the old theme's companion plugin, or rebuild that content with blocks.
Sources
- add_shortcode() WordPress Developer Resources
- do_shortcode() WordPress Developer Resources
- Shortcode block WordPress.org
- ob_start PHP Manual
- WooCommerce Shortcodes WooCommerce
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.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


