logo hsb.horse
← Back to blog index

Blog

Why /blog Returns 404 in Astro + bun dev and How to Fix It

A practical troubleshooting flow for /blog 404 under Astro + bun dev, from link checks to route output and delivery path inspection. Includes the directory-name collision fix.

Published: • Updated:
#astro #bun #troubleshooting #routing #i18n

Translations

German French Korean Japanese Portuguese

While running bun dev, /blog/ returned 404, but /en/blog/ rendered correctly.
The final cause was not routing configuration, but a directory-name collision.

Symptoms

  • http://localhost:4321/blog/ returns 404
  • http://localhost:4321/en/blog/ works
  • Production build (bun run build) still generates /blog/index.html

What I Suspected First

I first suspected link and locale path generation.

  • Is href: "/blog" in HeaderNav broken?
  • Is getLocalePath() behaving incorrectly only for Japanese?
  • Is /blog removed by prefixDefaultLocale: false behavior?

None of those were the problem.

Verification Process

I validated facts in this order:

  1. Check static output
    • bun run build logs include /blog/index.html
    • dist/blog/index.html actually exists
  2. Check rendered links
    • Nav link in dist/index.html is "/blog/"
    • Nav link in dist/en/index.html is "/en/blog/"
  3. Check i18n behavior
    • With prefixDefaultLocale: false, Japanese should be /blog/
    • /ja/blog/ being 404 is expected

At this point, route definition and link generation were confirmed correct.

Root Cause

There was a top-level blog/ directory used for article source files.
At the same time, page routing used src/pages/blog/index.astro.

So the real directory blog/ conflicted with URL segment /blog.
Under bun dev, this collision caused the 404.

Fix

  • Move article source files from blog/ to content/blog/
  • Update loader base in src/content.config.ts to ./content/blog

After this, /blog/ rendered correctly in bun dev.

Reusable Check Order

If the same issue appears again:

  1. Confirm bun run build generates /blog/index.html
  2. Confirm nav link in dist/index.html points to /blog/
  3. Confirm prefixDefaultLocale behavior and expected /ja/blog/
  4. Check for any project-root directory with the same name as the URL segment

Key Takeaways

  • Avoid using the same name for Astro URL segments and project-root directories
  • If build works but dev fails, compare delivery path behavior first
  • For 404 debugging, separate checks into link values, route generation, and actual files