Skip to content

Client-side navigation shows 404 on Vercel deployment, but page reload works correctly #1420

Description

@Arifulislam5577

Issue Body

Environment

  • Docus version: [latest]
  • Nuxt version: ^4.3.1
  • Deployment target: Vercel
  • Node.js version: v24.14.1
  • Package manager: bun - v1.3.14

Describe the bug

I built a documentation project using Docus and deployed it on Vercel. The deployment succeeds and the initial page loads correctly. However, there is a routing issue:

  • Direct page load (full reload / entering URL in address bar): The page renders correctly with all content.
  • Client-side navigation (clicking sidebar/internal links): Shows a 404 page instead of the target content.
  • After reloading the 404 page (F5 / hard refresh): The correct page content appears.

In short, the content exists and is served correctly on server-side/full page load, but client-side route transitions (SPA-style navigation) fail with a 404 error.


Steps to reproduce

  1. Clone the project: https://github.com/StaticMania/optim-ai-docs
  2. Deploy the project to Vercel (zero-config or standard Nuxt/Vercel setup)
  3. Visit the live site: https://optimai-docs.vercel.app/
  4. Click any sidebar/navigation link to navigate to another page
  5. Observe: 404 page is shown
  6. Reload the page (F5)
  7. Observe: Correct page content is now displayed

Expected behavior

Client-side navigation (clicking internal links in the sidebar or content) should render the target page without requiring a full page reload, just like it works in local development mode.


Actual behavior

  • Clicking any internal link / sidebar navigation triggers a 404 error page.
  • Reloading the page (hard refresh) shows the correct content.
  • This only happens on the Vercel deployment — local development (npm run dev) works perfectly.

Live Demo

🔗 Production URL: https://optimai-docs.vercel.app/


Additional context

  • This issue only occurs in the production deployment on Vercel.
  • Local development (dev mode) does not have this problem — all navigation works as expected.
  • The issue seems to be related to how client-side routing / payload fetching interacts with the Vercel deployment.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions