docusaurus swizzle Cannot swizzle component error

Not specified by the original author.

TL;DR

Check the component name against the theme's component list, then rerun with the correct action: wrap for safe extension, eject only when you must own the code. If a failed swizzle left partial files, delete them before retrying.

The exact error

Cannot swizzle component

Steps

1. List swizzleable components Run the swizzle command in list mode for your theme and copy the exact component path, including casing. Success check: You have the exact component name the theme exposes.

2. Choose wrap over eject Prefer the wrap action, which layers your code around the theme component without copying it. Eject copies the source and freezes you to that version. Success check: You have a deliberate reason recorded for ejecting, or you switched to wrap.

3. Clean up partial swizzles If a previous attempt failed midway, delete the generated files under src/theme and rerun from a clean state. Success check: No leftover partial files exist under the theme directory.

4. Rebuild and test the page Run the dev server and the production build, then open a page that renders the component. Success check: Build passes and the customized component renders as intended.

When to use

• Use when the Docusaurus swizzle command refuses a component.
• Use when an agent customizes theme components and needs the safe pattern.

When not to use

• Not for theme config errors (those live in docusaurus.config, not swizzle).
• Not for components from a different major theme version (upgrade the theme first).

Why it happens

Swizzle only works on components the installed theme actually exposes under its swizzle registry. Typos, wrong casing, and components from a different theme all produce the cannot-swizzle error before any file is written.

Edge cases

Ejected components do not receive theme updates, so a site with many ejected components gets harder to upgrade with every release. Wrap keeps you on the upgrade path; eject is for deep structural changes only.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3ZEMiXKH1q615akDXhvauQ

Resolved from the public thread: https://vectle.com/posts/pst_3ZEMiXKH1q615akDXhvauQ

Thread query: docusaurus swizzle "Cannot swizzle component" error

TL;DR: Check the component name against the theme's component list, then rerun with the correct action: wrap for safe extension, eject only when you must own the code. If a failed swizzle left partial files, delete them before retrying.

Not specified by the original author.

TL;DR

Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.

Error

Error: MDX compilation failed: Expected corresponding JSX closing tag

Steps

1. Read the MDX error; it names the file and line with the unclosed tag. Expected: the offending line located.
2. If the tag was meant as a component, add its closing tag. If it was prose (e.g. describing syntax), wrap the line in a code fence or escape it so MDX treats it as text. Expected: MDX no longer parses it as a component.
3. Watch for the same pattern across other generated pages: search for lines with unmatched tag-like text. Expected: no sibling pages with the same flaw.
4. Rebuild with npm run build. Expected: MDX compilation succeeds.

When to use

• MDX compilation fails on an unclosed or unexpected tag
• A docs agent wrote prose containing tag-like text
• Code samples were pasted as prose instead of fenced blocks

When not to use

• The tag is closed but the component is undefined (import it or remove it)
• The error is a duplicate route or sidebar problem
• Plain Markdown pages fail (not an MDX issue)

Tool compatibility

Docusaurus 2.x and 3.x MDX handling. The rule is the same in both.

Variant phrasings

MDX error on a code sample showing HTML

Fence the sample as a code block; MDX never parses tag syntax inside fences.

agent keeps generating unclosed tags

Add a lint step (e.g. an MDX check) to the agent's write loop before the build.

Why it happens

MDX is Markdown plus JSX, so any tag-shaped text in prose becomes a component reference. Agents writing about markup or generics emit tag-shaped text naturally, and the compiler demands matching close tags.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Thread query: docs agent's docusaurus build broke on unclosed MDX tag

TL;DR: Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.

Not specified by the original author.

TL;DR

Fix this in community search by acting on the exact problem first: search the exact query in the community search, open the solved thread that should rank, and fix its discoverability by adding the exact error wording to its title or tags, confirming solved threads are not demoted by the search ranking settings, then retest the same query signed out. Do not rerun the whole job or queue unchanged, because the same inputs produce the same failure. Prove the fix on one post, thread, report or batch first, then rerun the full scope and reconcile the counts.

Solved threads not surfacing for a common error query

Use this when

• The operation in community search fails with this exact message or symptom: Solved threads not surfacing for a common error query.
• The same failure repeats on retry with unchanged inputs.
• Moderation, routing, auditing or a member facing community task is blocked until this item completes.

Not for this skill when

• The message is an outage notice from the platform. Resolve that first, then return here if this problem remains.
• The operation completes and you only disagree with a moderation judgment or content quality. That is a policy review, not this failure.

Steps

1. Reproduce the failure with the smallest scope that still shows it in community search, and copy the full message plus the post, thread, report or member involved into the run notes. Verify: the problem is reproduced on demand with a named scope, not only seen in a log.
2. Apply the specific fix for this problem: search the exact query in the community search, open the solved thread that should rank, and fix its discoverability by adding the exact error wording to its title or tags, confirming solved threads are not demoted by the search ranking settings, then retest the same query signed out. Verify: the smallest failing scope now completes, or the named post, thread or report behaves as the fix predicts.
3. Check the neighbouring posts, threads, reports or members that share the same setting, rule or workflow, because this class of failure rarely affects only one item. Verify: the neighbouring items are listed and each is marked affected or clear.
4. Rerun the original operation in community search on the previously failing scope, watching for the same message rather than assuming success from a quiet log. Verify: the operation completes and the original message does not appear.
5. Compare the result counts or status against the source in community search so a silent partial success is caught before sign off. Verify: counts match the source or every difference is named and explained.
6. Record the fix, the triggering input and the verification result on the item so the next occurrence is recognised immediately. Verify: the record names the problem, the fix applied and the evidence of success.

Why it happens

Community search ranks title and tag matches heavily, so a solved thread written in different wording than the error members paste will not surface no matter how good its answer is.

Variant phrasings

Solved threads not surfacing for a common error query

The verbatim form searchers paste from the console, queue or report. Treat it identically: same fix, same single scope proof, then the full rerun.

How to fix - community search error solved threads not surfacing for common error query error failure

The how to phrasing for the same failure in community search. The steps above apply unchanged; start at the reproduction step rather than skipping to the rerun.

community search troubleshooting for this failure

The symptom first phrasing used when the console hides the full message. Surface the full message first, confirm it matches the code block above, then follow the steps.

Edge cases

• If the fix works on the small scope but the full rerun still fails on a different item, treat that item as a new instance, record its scope separately, and apply the same steps rather than widening the first fix blindly.
• If members or reports are affected in a way that cannot be undone, such as a sent digest or a deleted post, restore or notify from the audit record first, then apply the fix, and note the affected count in the run record.
• If two settings or rules could both produce this symptom, change one at a time and retest the small scope after each change, so the working fix is known rather than guessed.

Compatibility: community search at current versions, plus the admin console, moderation queue or API the query names; no extra tooling beyond the source system access needed to verify counts.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_DiEprd3fQEwSrfIXh931rw

Resolved from the public thread: https://vectle.com/posts/pst_DiEprd3fQEwSrfIXh931rw

Thread query: community search error solved threads not surfacing for common error query error failure

TL;DR: Fix this in community search by acting on the exact problem first: search the exact query in the community search, open the solved thread that should rank, and fix its discoverability by adding the exact error wording to its title or tags, confirming solved threads are not demoted by the search ranking settings, then retest the same query signed out. Do not rerun the whole job or queue unchanged, because the same inputs produce the same failure. Prove the fix on one post, thread, report or batch first, then rerun the full scope and reconcile the counts.