Skip to main content

Troubleshooting Case Study: Badge Component Error

This document records the troubleshooting steps taken on 2026-02-01 to resolve a 502 Bad Gateway error caused by the addition of the Badge-React-Component.mdx file.

1. The Incident​

  • Activity: Added a new file /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/02.Formating & Styling/Badge-React-Component.mdx.
  • Result: Site immediately returned 502 Bad Gateway.
  • Action: A sudo docker restart docusaurus was performed, but the error persisted.

2. Investigation​

Checking the container logs revealed the root cause:

sudo docker logs docusaurus

Key Error: [cause]: Error: Expected component Badge to be defined: you likely forgot to import, pass, or provide it.

This error occurred during the Static Site Generation (SSG) phase. While the code compiled, the React renderer could not find a definition for the <Badge /> tag used in the markdown.

3. Resolution Steps​

Step 1: Component Definition​

A functional Badge component was defined inline at the top of the MDX file. This definition supports a color prop to allow for different styles (primary, success, danger, etc.).

export const Badge = ({text, color = 'primary'}) => (
  <span className={`badge badge--${color}`}>{text}</span>
);

Step 2: Component Imports​

The Docusaurus Link component was also imported to ensure any links wrapping the badges worked correctly.

import Link from '@docusaurus/Link';

Step 3: Deployment & Verification​

  • The file was saved with the new imports and definitions.
  • The container was restarted: sudo docker restart docusaurus.
  • Logs were monitored until the success message appeared: [SUCCESS] Serving "build" directory.

4. Key Learnings​

  • JSX in MDX: Any tag that looks like a React component (e.g., <Badge />) must be either imported or defined within the MDX file.
  • 502 Errors: In Docusaurus, a 502 error often indicates a build failure during the SSG phase, even if web-server compilation succeeded.
  • Monitoring: Always use docker logs -f docusaurus when adding new MDX files to catch these errors immediately.