Skip to main content

Troubleshooting Guide

This guide helps you diagnose and fix common issues when deploying Docusaurus sites to Vercel.

Common Issue 1: Build Fails​

Symptoms​

  • Deployment shows a red "Failed" status
  • Build logs contain error messages
  • Site doesn't deploy or update

Possible Causes & Fixes​

Error Message:

Invalid sidebar file at "sidebars.js".
These sidebar document ids do not exist:
- devops-cloud-documentation/overview

Cause: Your sidebars.js references document IDs that don't match your actual file paths.

Fix:

  1. Check the error message for the list of invalid document IDs
  2. Compare them with your actual file structure in the docs/ folder
  3. Update sidebars.js to use the correct paths

Example: If your file is at docs/devops-cloud/setup.md, reference it as:

'devops-cloud/setup'  // Correct

Not as:

'devops-cloud-documentation/setup'  // Incorrect

Missing Dependencies​

Error Message:

Module not found: Can't resolve 'package-name'

Cause: A required package isn't listed in package.json or wasn't installed.

Fix:

  1. Test your build locally first:

    yarn build

  2. If the build works locally, ensure your package.json is committed

  3. If the build fails locally, install the missing package:

    yarn add package-name

  4. Commit and push the updated package.json

Node.js Version Incompatibility​

Error Message:

The engine "node" is incompatible with this module

Cause: Your project requires a specific Node.js version that doesn't match Vercel's default.

Fix:

  1. In Vercel dashboard, go to Project Settings → General
  2. Scroll to Node.js Version
  3. Select version 18.x or higher
  4. Trigger a new deployment by pushing a commit or clicking Redeploy

Package Manager Conflicts​

Warning Message:

Warning: package-lock.json found. Your project contains lock files generated by tools other than Yarn.

Cause: You have both package-lock.json (npm) and yarn.lock (Yarn) in your repository.

Fix:

  1. Choose one package manager (Yarn is recommended for Docusaurus)

  2. Delete the lock file for the package manager you're not using:

    # If using Yarn
    rm package-lock.json

    # If using npm
    rm yarn.lock

  3. Reinstall dependencies:

    yarn install  # or npm install

  4. Commit and push the changes

Symptoms​

  • Images don't load on deployed site (but work locally)
  • Internal links return 404 errors
  • CSS or JavaScript files missing

Possible Causes & Fixes​

Incorrect Base URL Configuration​

Cause: The baseUrl in docusaurus.config.js doesn't match your deployment path.

Fix:

  1. Open docusaurus.config.js

  2. Set the baseUrl to / for root-level deployments:

    module.exports = {
      baseUrl: '/',  // For yoursite.vercel.app
      // ...
    };

  3. If deploying to a subdirectory, include the path:

    module.exports = {
      baseUrl: '/docs/',  // For yoursite.vercel.app/docs
      // ...
    };

Wrong Asset Paths​

Cause: Images or files are referenced with incorrect paths.

Fix:

  1. Place all static assets in the static/ folder

  2. Reference them from the root:

    ![My Image](/img/my-image.png)

    Not:

    ![My Image](../static/img/my-image.png)

  3. The static/ folder contents are copied to the root of your site during build

Case Sensitivity Issues​

Cause: File names have different casing locally vs. in the repository (e.g., Setup.md vs. setup.md).

Fix:

  1. Ensure file names match exactly, including case

  2. Update all references in sidebars.js to match the actual file names

  3. Git doesn't always detect case-only changes, so you may need to:

    git mv docs/Setup.md docs/setup-temp.md
    git mv docs/setup-temp.md docs/setup.md
    git commit -m "Fix file name casing"

Common Issue 3: Wrong Build Command​

Symptoms​

  • Deployment succeeds but site shows Vercel's default page
  • Build output directory is empty or incorrect
  • Old content appears instead of latest changes

Possible Causes & Fixes​

Incorrect Build Command​

Cause: Vercel is using the wrong command to build your site.

Fix:

  1. Go to your Vercel project dashboard
  2. Click Settings → General
  3. Scroll to Build & Development Settings
  4. Click Override next to Build Command
  5. Enter the correct command:
    • For Yarn: yarn build
    • For npm: npm run build
  6. Click Save
  7. Trigger a redeploy by going to Deployments → click the three dots on the latest deployment → Redeploy

Wrong Output Directory​

Cause: Vercel is looking for build output in the wrong folder.

Fix:

  1. In Settings → General → Build & Development Settings
  2. Click Override next to Output Directory
  3. Enter build (Docusaurus's default output directory)
  4. Click Save
  5. Redeploy your site

Build Command Not Running​

Cause: The install command failed, so the build command never ran.

Fix:

  1. Check the build logs for install errors

  2. Verify your package.json is valid JSON (use a validator like jsonlint.com)

  3. Ensure all dependencies are correctly specified:

    {
      "scripts": {
        "build": "docusaurus build"
      },
      "dependencies": {
        "@docusaurus/core": "^3.0.0",
        "@docusaurus/preset-classic": "^3.0.0"
      }
    }

Additional Debugging Tips​

Test Builds Locally First​

Always run a production build locally before deploying:

yarn build
yarn serve

This catches most issues before they reach Vercel.

Check Build Logs​

Vercel provides detailed build logs:

  1. Go to Deployments in your project dashboard
  2. Click on the failed deployment
  3. Click View Build Logs
  4. Look for error messages (usually in red)

Clear Build Cache​

Sometimes old cached files cause issues:

  1. Go to Settings → General
  2. Scroll to Build & Development Settings
  3. Click Override and check Clear cache
  4. Trigger a new deployment

Environment Variables​

If your site requires environment variables:

  1. Go to Settings → Environment Variables
  2. Add required variables with their values
  3. Select which environments to apply them to (Production, Preview, Development)
  4. Redeploy your site

Getting Help​

If you're still experiencing issues: