Skip to main content

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.

1. The "Dependency Trap"​

The Problem​

Docusaurus is not just a collection of markdown files; it is a compiled React application. References to files are often "hard-coded" in configuration files by their Document ID.

If you delete a file (e.g., knowledge/docusaurus/index.md) but your docusaurus.config.js still tries to create a Navbar link to it, the build engine will throw a fatal error.

Common Symptom​

The Docker container starts, but logs show:

Error: Couldn't find any doc with id "knowledge/docusaurus/index" in version "current".

Because the build fails, the web server never starts, and Cloudflare/Nginx returns a 502 error.

2. Proper Way to Hide Sidebar Items (Safe Method)​

If your goal is to remove an item from the Sidebar while keeping it active for the Navbar or other links, do not delete the file. Instead, use one of these three methods:

This keeps the file fully functional but tells the sidebar generator to ignore it.

  1. Open the .md file.
  2. Add this to the frontmatter:
---
title: My Page
sidebar_class_name: hidden
---
  1. Restart the container.

Method B: unlisted: true (Docusaurus v3+)​

This removes the page from the sidebar, sitemap, and search, but keeps the URL active.

---
unlisted: true
---

Method C: Move to _category_.json​

If you are trying to hide an "Index" page that represents a folder, you can often achieve this by configuring the category itself to be "linked" rather than have a separate file.

3. How to Safely Delete a File​

If you truly want a file gone from the system entirely, follow this strict 3-step sequence:

Step 1: Search for References​

Before deleting my-file.md, search your codebase for its ID:

grep -r "my-file" /opt/docker-data/apps/docusaurus/site/

Step 2: Clean up docusaurus.config.js​

Check these sections in your config:

  • Navbar Items: Look for docId: 'my-file'.
  • Footer Links: Look for to: 'docs/my-file'.

Change these links to point to an existing document or remove the entry entirely.

Step 3: Delete and Restart​

rm docs/my-file.md
sudo docker restart docusaurus

4. Recovery: What to do if the site is already down​

If you deleted a file and the site is now returning 502:

Step 1: Identify the missing ID​

Check the logs to see exactly which file Docusaurus is looking for:

sudo docker logs docusaurus | grep "Couldn't find any doc with id"

Step 2: Emergency Restore​

Create a placeholder file at the expected path to satisfy the build:

# Example if "intro" was deleted
echo "# Placeholder" > /opt/docker-data/apps/docusaurus/site/docs/intro.md

Step 3: Restart and Clean Up​

Restart the container. The site should come back up. Now you can properly update your docusaurus.config.js and delete the placeholder safely.

Troubleshooting Checklist​

  • Check Logs: Run sudo docker logs docusaurus --tail 50.
  • Verify IDs: Does the ID in docusaurus.config.js match the file path? (e.g., knowledge/test/doc.md -> ID: knowledge/test/doc).
  • Check Sidebars: If you use a manual sidebars.js, ensure the deleted file is removed from there too.
  • Verify Extensions: Docusaurus expects .md or .mdx. Ensure you didn't accidentally rename a file to .txt or something else.
  • Rebuild Cache: If errors persist after fixing references: 
    sudo docker exec docusaurus rm -rf .docusaurus
    sudo docker restart docusaurus

Summary Table: How to Remove Items​

GoalActionRisk
Hide from Sidebar onlyAdd sidebar_class_name: hiddenNo Risk (Safe)
Hide from Search/SidebarAdd unlisted: trueNo Risk (Safe)
Remove from Site completelyDelete file + Update docusaurus.config.jsHigh Risk (Build may fail)
Remove FolderDelete folder + Check recursive linksHigh Risk