Troubleshooting

Quick fixes for problems you may hit while working on this documentation site (Docusaurus 3, OpenAPI plugin, custom sidebars).

Build fails with “Unable to build website for locale en”

1. Scroll to the first error in the terminal output. Docusaurus often reports a cause (invalid doc id, broken link, MDX error).
2. Typical causes in this repo:
   • Invalid doc id in a generated sidebar.ts under docs/openapi/... — the id must match a real document the classic docs plugin knows about.
   • Broken links — internal links must match the route Docusaurus generates (including path segments for nested OpenAPI folders).
   • MDX compilation errors — see Broken MDX or images.

After fixing, run:

bash
pnpm build

“OpenAPI docs plugin ID must be specified when more than one plugin instance exists”

This project registers several docusaurus-plugin-openapi-docs instances in docusaurus.config.ts. You must pass the plugin id and the config key for the spec you want to generate.

Example pattern (adjust id and key to match your entry in the config):

bash
# Worker (~3200)
pnpm gen-api-docs:notification-worker
​
# Orchestrator (~3210)
pnpm gen-api-docs:notification-orchestrator

Equivalente explícito:

bash
pnpm docusaurus gen-api-docs notification-service notificationService
pnpm docusaurus gen-api-docs orchestrator-message-service orchestratorMessageService

List the plugin blocks in docusaurus.config.ts and use each block’s id and the key inside config: { ... }.

For all specs (if your setup supports it):

bash
pnpm gen-api-docs

pnpm gen-api-docs -p <plugin-id> does not create subfolders

When you generate docs for a single OpenAPI plugin instance, for example:

bash
pnpm gen-api-docs -p <plugin-id>

(replace <plugin-id> with the unique id from the corresponding block in docusaurus.config.ts)

the command does not create intermediate subfolders under outputDir. If your layout relies on nested directories (for example tag-based groups under docs/openapi/<service>/…), create those folders yourself before running pnpm gen-api-docs -p …. Otherwise generation may fail or write files where the rest of the site does not expect them.

API docs generated but routes do not appear in the sidebar

1. Confirm files were written under the expected outputDir (see the plugin config in docusaurus.config.ts).
2. Open the generated sidebar.ts in that folder (or subfolders when using groupPathsBy: 'tag').
3. Register those sidebar files in the root sidebars.ts under apiSidebar, as described in Add Items to Sidebar.
4. Restart the dev server after adding new files: stop pnpm start and start again so Node can require() new modules.

“Cannot find module …/sidebar.ts”

The OpenAPI plugin or root sidebars.ts references a path that does not exist yet.

• Run the appropriate gen-api-docs command so the file is created, or
• Remove or fix the require(...) path in sidebars.ts until the file exists.

Then restart pnpm start.

Sidebar looks duplicated or shows raw route segments

Usually the generated sidebar.ts mixes top-level doc items with categories that repeat the same labels. Prefer only categories (or a single consistent structure) inside each sidebar.ts, and ensure doc ids match the generated MDX frontmatter. Re-run pnpm build to validate.

Error: useDocsSidebar / DocsSidebarProvider when opening a sidebar item

Custom OpenAPI tag pages (*.tag.mdx) must not call React hooks (for example useCurrentSidebarCategory) inside a fenced mdx-code-block section. That runs the code outside the normal doc layout context.

Render DocCardList and hooks as normal MDX/JSX in the file body, not inside mdx-code-block.

Broken MDX or images

• Images: use paths relative to the MDX file, or place assets under static/ and reference them with a leading /.
• Trailing underscores or broken filenames in image URLs often fail resolution — rename the file and update the markdown to match exactly.

Port already in use (Something is already running on port 3000)

Either stop the other process or accept another port when the CLI prompts you. The site URL will be shown in the terminal (for example http://localhost:3002/).

Still stuck

1. Run pnpm build and capture the full first error block.
2. Check docusaurus.config.ts for the plugin id and outputDir you are working with.
3. Compare doc ids in sidebars.ts with the id in the frontmatter of the target .mdx / .md files.