WP-CLI 502 Error Fix
Issue Description
Tunnel 502 Recovery Log
This document records exactly what was done to restore brain.id86.net after a 502 incident in a Docker + Cloudflare Tunnel + Zero Trust setup.
Post-Restart 502 (Build Window)
This report documents the incident where brain.id86.net returned 502 Bad Gateway right after restarting the docusaurus container.
02 Recovery - `cd.mdx` Frontmatter
This incident report documents a new brain.id86.net 502 case where Docusaurus failed to start because of invalid frontmatter in one doc file.
02 YAML Frontmatter (Ads Docs)
This document records the incident where brain.id86.net returned 502 Bad Gateway after restarting the docusaurus container, and the fix that restored service.
GSheet 502 Recovery
This incident report documents the 502 error observed on brain.id86.net after restarting the Docusaurus container during Google Sheet migration rollout.
Idle Bloat - Build on Start
This report documents a production hardening case where the site appeared "bloated" even without active user browsing.
find.mdx 502 Parse Error
This report documents a 502 Bad Gateway incident on brain.id86.net caused by a Docusaurus MDX parse failure in find.mdx.
Idle Bloat + Dark Mode Fix
This incident documents a follow-up case where the site felt bloated while idle and dark mode appeared not to activate.
TabItem ListItem Build Failure
This report documents a Docusaurus build failure caused by markdown list items (- ) placed inside ` JSX components across 26 .mdx` files.
Incident Report (Mermaid + 502)
This report summarizes the issues found during troubleshooting and the fixes applied to restore service stability.
brain.id86.net 404 Recovery
This guide documents the maintenance steps used to restore brain.id86.net when the site was reachable through Cloudflare Access but returned a 404 the requested path could not be found error after login.
Linux Server Docs Build Failures (Mar 2026)
Post-incident report covering six MDX/YAML build failures found during linux-server documentation rewrite: inverted frontmatter, unquoted colons, JSX inside list items, bare angle brackets, missing TabItem imports, and missing Prism language support.
brain.id86.net Wrong Container Recovery
This incident report documents how https://brain.id86.net/docs/server/linux-server/ was restored after it started serving placeholder content instead of the production Linux Server documentation.
Sidebar Label and Redundancy Troubleshooting
This guide explains how we fixed the issue with folder names not appearing correctly in the sidebar and how to handle redundant names.
Troubleshooting 502 Bad Gateway Errors
A 502 Bad Gateway error typically occurs when the entry point (Cloudflare, Nginx, or a Load Balancer) is unable to connect to the backend Docusaurus service. In your Docker environment, this usually means the container is either down, still starting up, or has crashed due to a configuration error.
Badge Component Case
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.
Broken Media Paths
This guide explains why Docusaurus builds fail (502 errors) when adding images or videos, and how to use the correct path structure.
Mermaid Integration
This guide addresses specific issues that may arise when integrating the Mermaid.js plugin into Docusaurus and how to resolve the resulting 502 Bad Gateway errors.
Onboarding Runtime Incident
This report documents the issues encountered during 01. Server-onboarding migration and the exact fixes applied.
Troubleshooting: 502 Errors After Deleting or Moving Files
When you remove or move a file in Docusaurus, you might expect the sidebar to simply update. However, if that file is referenced elsewhere in your configuration (like the Navbar), the entire site build will fail, resulting in a persistent 502 Bad Gateway error and a container restart loop.
Undefined Components
This guide explains how to identify and fix build failures caused by using React components in .mdx files without importing or defining them.
YAML Syntax & Links
This guide covers a specific case where a 502 Bad Gateway error was caused by a build failure due to invalid YAML frontmatter syntax and broken internal links after a file extension conversion.
Why New Folders Are Not Updating on the Front End
When you add a new folder to your Docusaurus documentation (e.g., /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/), but it doesn't appear on the live site, there are several potential causes and solutions. This guide provides comprehensive troubleshooting steps based on real-world scenarios.