Shortcodes are WordPress’s native macro system: bracketed tokens like that expand into server-rendered output at runtime. When a shortcode breaks, the failure usually appears as raw bracket text in the front end, a blank section where a form or gallery should be, or a fatal error during do_shortcode(). For small-to-mid publishing teams that maintain their own production installs, the practical problem is not just fixing the renderer. It is recovering what the shortcode was supposed to do when the plugin is gone, the callback is missing, or the original attributes were never documented. This article shows how to reconstruct that intent from post content alone, using reproducible SQL, WP-CLI, and block-editor inspection techniques.
This matters because shortcode failures are often treated as plugin problems, but the real damage is editorial. A broken [pullquote] or [chart] leaves a hole in an article that may have been live for years. If you cannot recover the original intent, you either delete the token and lose the embedded meaning, or you guess and risk changing the article’s structure. The methods below are evidence-driven: they start with the stored post content, not with assumptions about the plugin that created it.
Start With the Stored Post Content, Not the Rendered Page
The first step is to inspect the raw post_content field. The rendered page may hide the shortcode behind a blank div, a cached fragment, or a fatal error. The database row is the source of truth.
SELECT ID, post_title, post_status, post_content
FROM wp_posts
WHERE post_content LIKE '%[%'
AND post_status = 'publish'
ORDER BY post_modified DESC
LIMIT 50;This query returns every published post that contains at least one opening square bracket. It is intentionally broad because broken shortcodes are not always obvious. A shortcode can be nested inside a block comment, a custom HTML block, or a classic editor paragraph. The raw content shows the exact token, its attributes, and any surrounding text that hints at its purpose.
If you prefer WP-CLI, the equivalent is:
wp post list --post_type=post --post_status=publish --fields=ID,post_title,post_content --format=json | grep -B2 -A2 '\['This is slower on large databases but useful when you need to pipe results into a file for diffing against a backup.
Identify the Shortcode Signature and Its Attribute Shape
Once you have the raw token, record its exact signature. A shortcode like [product id="42" sku="ABC-123"] tells you three things: the tag name, the attribute keys, and the attribute values. The tag name is the strongest clue. It usually matches the plugin slug, the developer’s namespace, or a feature name.
For example, is a core shortcode. [contact-form-7] is plugin-specific. [et_pb_section] is Divi. [vc_row] is WPBakery. If the tag is custom, search the active theme and plugin directories for the string add_shortcode(:
grep -R "add_shortcode" wp-content/plugins wp-content/themesIf the callback is missing, the shortcode will not render. But the attribute shape still tells you what the original author intended. A shortcode with ids="12,34,56" was almost certainly pulling specific posts or attachments. A shortcode with category="news" count="5" was a query loop. A shortcode with title="" class="" was probably a wrapper for styling.
Recover Attribute Semantics From Adjacent Content
Look at the text immediately before and after the shortcode in post_content. Authors often write a lead-in sentence that explains what the shortcode should show. For example:
Here are the top five posts from the archives:
[top_posts count="5" category="archives"]
The lead-in gives you the semantic intent: a list of five posts from the archives category. Even if the shortcode callback is gone, you can replace it with a core block or a simple WP_Query loop that matches that intent.
If the shortcode is self-closing and has no adjacent text, check the post’s revision history. The original version may have included a plain-text placeholder before the shortcode was inserted.
SELECT wp_posts.ID, wp_posts.post_title, wp_posts.post_content
FROM wp_posts
WHERE wp_posts.post_type = 'revision'
AND wp_posts.post_parent = 123
ORDER BY wp_posts.post_date ASC;Replace 123 with the post ID. Revisions often preserve the pre-shortcode text, which can reveal the author’s original wording.
Map the Shortcode to a Known Plugin or Core Feature
WordPress core ships with a small set of shortcodes: , , , , , and . If the broken token matches one of these, the fix is usually a theme or plugin conflict, not a missing callback. The Shortcode API documentation lists the core tags and their default attributes.
For plugin-specific shortcodes, the plugin’s readme or source code is the best reference. If the plugin is still installed but deactivated, reactivate it temporarily and inspect the rendered output. If the plugin was deleted, check the WordPress.org plugin repository or the developer’s documentation. The tag name is often enough to find the original plugin.
If the shortcode is from a commercial theme or page builder, the attribute names are usually documented in the theme’s help files. For example, a broken [et_pb_section] token with background_color="#f5f5f5" and padding_top="20px" tells you it was a full-width section with a light gray background and 20 pixels of top padding. That is enough to rebuild the section as a group block with the same spacing and background.
Reconstruct the Intent From Attribute Values Alone
When the tag name is unknown and the plugin is gone, the attribute values are your only evidence. Treat them as a data contract. Each key-value pair is a constraint on what the shortcode was supposed to do.
Here is a practical example. A post contains this token:
[display_posts items="3" type="portfolio" order="date" direction="desc"]The tag display_posts is generic, but the attributes are specific. items="3" means it displayed three items. type="portfolio" means it filtered by a custom post type or taxonomy called portfolio. order="date" and direction="desc" mean it sorted by date, newest first. The reconstruction is a query loop that pulls the three most recent portfolio items. You can implement that with a core Query Loop block or a small custom shortcode that matches the original attribute names.
This approach works because shortcode authors tend to use attribute names that mirror WordPress query parameters. posts_per_page, category, tag, orderby, and order are common. If the attribute names are cryptic, check the post’s other shortcodes. The same author may have used the same plugin elsewhere with more descriptive attributes.
Use the Block Editor as a Reconstruction Sandbox
Once you have a hypothesis about the shortcode’s intent, test it in the block editor before touching the live post. Create a new draft, add a shortcode block with the original token, and preview the output. If the shortcode is still registered, you will see the rendered result. If it is broken, the block will show the raw token, which confirms the failure.
Then replace the shortcode block with the equivalent core blocks. For a gallery shortcode, use the Gallery block. For a query loop, use the Query Loop block. For a pullquote, use the Pullquote block. The block editor’s block markup is stored as HTML comments in post_content, so you can compare the before and after versions with a diff tool.
This sandbox approach is safer than editing the live post directly. It also gives you a visual check: if the reconstructed blocks look wrong, your attribute interpretation was probably wrong.
Query the Database for Shortcode Usage Patterns
If the same broken shortcode appears in multiple posts, aggregate the attribute values to find the most common configuration. This is especially useful for shortcodes that were used as templates, like a call-to-action box or a related-posts widget.
SELECT
SUBSTRING_INDEX(SUBSTRING_INDEX(post_content, '[', -1), ']', 1) AS shortcode_token,
COUNT(*) AS usage_count
FROM wp_posts
WHERE post_content LIKE '%[%'
AND post_status = 'publish'
GROUP BY shortcode_token
ORDER BY usage_count DESC
LIMIT 20;This query is crude because it only captures the first shortcode in each post, but it gives you a frequency map. For a more precise extraction, use a script that parses all shortcode tokens with a regular expression. The pattern /\[(\w+)([^\]]*)\]/ matches the tag name and attribute string for most shortcodes.
Once you have the frequency map, focus on the most common token. That is the shortcode that caused the most editorial damage. Reconstruct its intent first, then apply the same fix to all affected posts with a SQL update or a WP-CLI search-replace.
Reconstructing a Shortcode That Wrapped Content
Enclosing shortcodes are harder to reconstruct because the wrapped content is part of the intent. A token like [note]This is important.[/note] tells you two things: the shortcode wrapped a piece of text, and the text itself is the content. The reconstruction is a styled block that preserves the text.
In the block editor, the equivalent is a Group block with a custom class, or a Paragraph block with a background color. The key is to preserve the wrapped text exactly. Do not paraphrase or summarize it. The original author chose those words for a reason.
If the enclosing shortcode had attributes, they usually control the wrapper’s appearance. [note color="red"] means the note should have a red border or background. [box title="Warning"] means the box should have a visible title. Reconstruct those visual cues with block styles or a small CSS class.
When the Shortcode Is a Data Source, Not a Renderer
Some shortcodes are not visual. They pull data from an external API, a custom table, or a transient. A broken [stock_price symbol="AAPL"] token is not a styling problem. It is a data pipeline problem. The reconstruction is not a block replacement; it is a decision about whether the data is still available and whether the article still needs it.
In these cases, the attribute values are the data contract. symbol="AAPL" means the shortcode was fetching the current price of Apple stock. If the data source is gone, the article has a factual hole. You have two options: remove the token and add a plain-text note, or replace it with a static value that was correct at the time of publication. The second option is better for archival integrity, but it requires a source for the historical value.
Check the post’s revision history for a cached version of the rendered output. If the shortcode was rendered before it broke, the revision may contain the final HTML. That HTML is the most accurate reconstruction you can get.
SELECT post_content
FROM wp_posts
WHERE post_type = 'revision'
AND post_parent = 123
AND post_content LIKE '%stock_price%'
ORDER BY post_date DESC
LIMIT 1;If the revision contains the rendered HTML, copy it into the live post as a custom HTML block. That preserves the original output without depending on the broken shortcode.
Document the Reconstruction for Future Editors
After you reconstruct a shortcode’s intent, document it. A shortcode that broke once will break again if the same plugin is removed or the same theme is changed. The documentation should live in the post itself, not in a separate wiki. A simple HTML comment at the top of the post content is enough:
<!-- Reconstructed from [display_posts items="3" type="portfolio"] on 2025-01-15. Original plugin: Portfolio Display. Replacement: Query Loop block. -->This comment is invisible to readers but visible to anyone who edits the post in the code editor. It records the original token, the reconstruction date, and the replacement method. That is the kind of durable documentation that prevents the same failure from happening twice.
For a broader fix, create a site-specific plugin that registers the missing shortcode with a simple fallback. If the original plugin is gone, the fallback can render a plain-text version of the shortcode’s attributes. That keeps the post content intact while you work on a permanent replacement.
add_shortcode( 'display_posts', function( $atts ) {
$atts = shortcode_atts( array(
'items' => 3,
'type' => 'portfolio',
), $atts );
return sprintf( '<!-- Reconstructed display_posts shortcode: %s -->', esc_html( wp_json_encode( $atts ) ) );
} );This fallback does not render the original output, but it preserves the attribute data in the HTML source. That is enough for a future editor to understand what the shortcode was supposed to do.
Common Failure Modes and Their Reconstructions
Here are three real failure modes I have seen in production installs, with the reconstruction method for each.
1. Plugin Deactivated, Shortcode Left Behind
A site used a plugin called related-posts-widget that registered [related_posts]. The plugin was deactivated during a cleanup, and every post that used the shortcode started showing raw bracket text. The fix was to query all posts with [related_posts], extract the count and category attributes, and replace the token with a core Query Loop block that matched the same parameters. The reconstruction took about an hour for 40 posts.
2. Theme Change Removed a Page Builder Shortcode
A site moved from a commercial theme to a block theme. The old theme used [section] shortcodes for layout. The new theme ignored them, leaving blank spaces in the content. The reconstruction involved parsing each [section] token’s attributes, mapping them to Group block spacing and background settings, and rebuilding the layout in the block editor. The attribute names were the key: padding, background, and columns mapped directly to block settings.
3. Shortcode Callback Fatal Error
A custom shortcode [chart] called a PHP function that used a deprecated API. The function threw a fatal error, which broke the entire page. The fix was to remove the shortcode callback and replace the token with a static image of the chart. The image was recovered from the site’s media library, where the original chart had been uploaded as an attachment. The post content was updated with a core Image block pointing to that attachment.
FAQ
How do I find all posts that contain a specific broken shortcode?
Use a SQL query with a LIKE pattern that matches the shortcode tag. For example, to find all posts with [display_posts, run:
SELECT ID, post_title, post_status
FROM wp_posts
WHERE post_content LIKE '%[display_posts%'
AND post_status = 'publish';This returns every published post that contains the token, including posts where the shortcode is nested inside other content. For a more precise match, include the closing bracket in the pattern: '%[display_posts %' or '%[display_posts]%'.
Can I recover the rendered output of a broken shortcode from a backup?
Yes, if the backup was taken before the shortcode broke. Restore the backup to a staging environment, then view the affected post. The rendered output is the most accurate reconstruction you can get. Copy the HTML into the live post as a custom HTML block. If you do not have a full backup, check the post’s revision history. Revisions sometimes contain the rendered output from before the shortcode was broken.
What is the safest way to replace a broken shortcode in a live post?
Create a draft copy of the post, make the replacement in the draft, and preview it before publishing. This gives you a side-by-side comparison of the old and new content. If the replacement looks wrong, discard the draft and try a different interpretation of the shortcode’s attributes. Never edit the live post directly when you are unsure about the shortcode’s intent.
How do I prevent shortcode breakage in the future?
Document every shortcode your site uses, including its tag name, attributes, and the plugin or theme that registers it. Store this documentation in a site-specific plugin or a private page on the site. When you deactivate a plugin or change themes, run a search for its shortcodes before making the change. The query in the first section of this article is a good starting point.
For more on diagnosing WordPress content problems, see What to Fix First When a New WordPress Site Says Nothing Found.
