Plain install with defaults displays 404 errors

[SimonEast]

Describe the bug

When creating a plain vanilla npm install -D vitepress and vitepress init, the development site shows a 404 error. This occurs for both the homepage / and /markdown-examples.html.

I'm using the latest versions of vitepress (1.5.0), node (23.5.0), and npm (11.0.0), on Windows 10.

Reproduction

1. Create an empty folder for the project
2. Run npm install -D vitepress
3. Run npx vitepress init
4. Choose all the default options
5. Run npm run docs:dev
6. Dev server appears to run successfully, with no errors shown, but browser displays a 404.

Unfortunately when I run the exact same commands on Stackblitz, it works perfectly. So it must be something with my environment.

I've tried changing the settings during vitepress init to use a subfolder and disable TypeScript, but all variations so far produce the same problem.

The following errors are displayed in the browser console:

Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/markdown". Strict MIME type checking is enforced for module scripts per HTML spec.
router.js?v=f6c1eb47:88

TypeError: Failed to resolve module specifier '.md?import&t=1735454575539'
at index.js:121:52
at async loadPage (router.js?v=f6c1eb47:39:24)
at async Object.go (router.js?v=f6c1eb47:29:9)

Expected behavior

I would expect the default homepage to be displayed. Instead a 404 error is shown.

System Info

System:
    OS: Windows 10 10.0.19045
    CPU: (16) x64 AMD Ryzen 7 5700G with Radeon Graphics
    Memory: 4.66 GB / 31.30 GB
  Binaries:
    Node: 23.5.0 - C:\Program Files\nodejs\node.EXE
    Yarn: 3.5.1 - C:\Program Files\nodejs\yarn.CMD
    npm: 11.0.0 - C:\Program Files\nodejs\npm.CMD
    pnpm: 9.1.2 - C:\Program Files\nodejs\pnpm.CMD
  Browsers:
    Chrome: 130.0.6723.117
    Edge: Spartan (44.19041.3570.0), Chromium (110.0.1587.50)    
    Internet Explorer: 11.0.19041.3570

Additional context

Here is the exact output from my terminal window, starting from an empty folder:

npm install vitepress -D

added 126 packages in 5s

39 packages are looking for funding
  run `npm fund` for details

npx vitepress init

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.


npm run docs:dev

> docs:dev
> vitepress dev docs


  vitepress v1.5.0

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

Validations

• Check if you're on the latest VitePress version.
• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

[brc-dd]

Can you check if your anti-virus is blocking something?

[SimonEast]

I only use the standard Windows Defender anti-virus, although I do have "Controlled Folder Access" enabled for tighter security, but my dev folder is outside the protected folders so I don't think it should be impacted. I tried disabling my firewall, but it made no difference.

A strange thing I noticed is that after running the dev server, the console error leads me to http://localhost:5173/index.md?import&t=17354566042697, which if I load this directly in my browser:

• My problematic Windows 10 install displays a plain markdown file
• My StackBlitz install displays the markdown file encoded in JavaScript

This appears to be a key part of the issue. So it's obviously finding the file correctly, I'm just not sure why it's delivering plain markdown instead of bundling as JS. 🤔

[brc-dd]

Can you check if vue/vite apps work fine? npm create vue@latest 👀

[brc-dd]

Seems to work fine for me:

Maybe try re-installing node or something.

[SimonEast]

After a couple of hours of troubleshooting this I think I worked out the issue. I created a new blank folder on a different drive and everything worked correctly as expected.

I realised that the troublesome dev folder I was working in was inside an NTFS junction (kind of like a symlink), which I suspect Vite cannot traverse/resolve.

For example, I was working inside:
D:\Dev\Vitepress Project
But
D:\Dev is actually a junction pointing to J:\Dev (on a different drive).
If I run the commands on J: instead of D: then everything works correctly.

Sorry to trouble you with the issue. But I guess it's good to document here in case someone else experiences a similar issue in future.

It seems to be a problem with Vite, as mentioned in this Svelte issue: sveltejs/kit#3579

I don't think a Vite issue has been raised for this yet. Maybe I will submit one.

Will close this issue for now.