Subpath: This route collides with: "src/pages/404.astro".

[rwieruch]

What version of starlight are you using?

0.12.1

What version of astro are you using?

3.3.0

What package manager are you using?

yarn

What operating system are you using?

Mac

What browser are you using?

Chrome

Describe the Bug

I already used Astro for my website and wanted to integrate Astro Starlight manually to it for my "Help Desk". When I tried to start it, I got the following error:

This route collides with: "src/pages/404.astro".

Because Astro Starlight comes with a 404 as well, I had to remove my top-level 404 page. It works, however, are there any plans to allow two 404 if Starlight gets dropped in as a subpath?

Thanks for all your work here!

Link to Minimal Reproducible Example

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thank you for the issue @rwieruch! This is a known problem, but we don’t really have an issue tracking it, so this is helpful.

We have definitely spoken about fixing this for the subpath use case in #966 although even then it’s not entirely clear if Starlight should always avoid injecting the 404 page.

The simple option is to add a configuration flag that controls whether we inject our 404 route. That way you could disable the 404 in cases where you have your own.

I held off from doing that in the hope that we could use our main injected route also for 404s. We currently inject these separately:

starlight/packages/starlight/index.ts

Lines 31 to 38 in b1ab354

	injectRoute({
	pattern: '404',
	entryPoint: '@astrojs/starlight/404.astro',
	});
	injectRoute({
	pattern: '[...slug]',
	entryPoint: '@astrojs/starlight/index.astro',
	});

Due to how Astro’s route priority works, if we generated the 404 using the [...slug] route, a user’s 404 would take precedence. Last I tested, this hit a small bug in dev mode where Astro wouldn’t use the dynamically routed 404. I’ll take a look to see if that’s still the case — would be the ideal solution in my opinion, because no config is required, we would simply respect your project’s custom 404 automatically.

[rwieruch]

Thanks for the quick reply @delucis

I think opt-ing out Starlights 404 is okay. Perhaps it would be even better to serve the Starlights 404 only if something within the subpath does not match. If soemthing is not found outside of the subpath, meaning outside Starlight, it shoudl show the top-level 404.

I come to this conclusion because the top-level website looks different from Starlight, so it should be okay to show the 404 within each's context for aesthetic reasons.

[delucis]

Perhaps it would be even better to serve the Starlights 404 only if something within the subpath does not match.

That’s probably outside of our control unfortunately without users setting up some custom config on their host. Most static hosts just treat a root 404.html as the 404 page and don’t support multiple. You can work around this with custom config — we do this for multilingual 404s in Starlight’s docs for example — but we couldn’t offer it as a default “works everywhere” behaviour.

Example configs

netlify.toml

[[redirects]]
  from = "/:lang/*"
  to = "/:lang/404/"
  status = 404

vercel.json

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "routes": [
    { "src": "/(?<lang>[^/]*)/(.*)", "dest": "/$lang/404/", "status": 404 }
  ]
}

(Unfortunately requires Vercel’s deprecated routes config from what I’ve gathered.)

[rwieruch]

Thanks for the insights and your time @delucis Very much appreciated! For my case everything works fine and I am amazed how smoothly the Starlight integration went for my existing Astro website. This was next level! Feel free to close this issue or to move it to the discussion section of GitHub :)

[delucis]

Just tested, and the same limitation around moving this to the dynamic route still exists in Astro. I’m going to talk to the team to see if this is something we can fix upstream. If it isn’t, we can look at adding a flag to disable Starlight’s 404 injection.

---

^{🔗 Internal discussion reference for Astro maintainers}

[abs]

My project [ab]uses the 404.astro page to load the SPA:

I've been looking for workarounds, but so far it's all looking pretty bleak :)

If there was an easy way to turn off Starlight's 404 injection, it would help a ton.

[delucis]

If there was an easy way to turn off Starlight's 404 injection, it would help a ton.

We’ve been discussing it — hopefully will know more next week!

In the meantime, you could add another level of hackiness by loading your SPA from src/content/docs/404.mdx:

---
title: My SPA
---

import SPA from '../../SPA.astro';

<SPA client:load />

[abs]

In the meantime, you could add another level of hackiness by loading your SPA from src/content/docs/404.mdx:

I did try that, but of course it loads the SPA from inside Starlight (instead of its 404), which is... suboptimal, to put it mildly :-)

I've unblocked our docs development by using a fork - abs@db448f4

Once y'all come up with a fix, I'd be happy to give it a go!

[delucis]

Ohhhh, yeah of course 😅

Will let everyone know more here next week 🙌

[olton]

Hello. Any news on how to fix this? This route collides with: "src/pages/404.astro"

[delucis]

Fair question! No progress just yet, but withastro/astro#9439 will allow us to fix this really nicely by enabling us to set a lower priority on Starlight’s injected 404 route. This would let user 404s take over if they exist.

withastro/astro#9439 is a larger PR to Astro and we’re heading towards the holiday period, so I don’t want to promise too much with regards to the timeline, but at least a solution is on the horizon!

[delucis]

withastro/astro#9439 ended up taking a different direction and won’t help with this, so I think it’s time to add a configuration flag to help unblock folks on this — we can always remove the flag in the future if we have better options.

Would someone like to contribute a PR? I’d suggest something like:

1. Add an option for disabling 404 rendering to the user config

2. Skip the injectRoute() call if that is set

3. Update configuration reference with the new option and maybe also the “Custom 404 page” section in the docs

[connor-baer]

I'd be happy to take a stab at it. Thanks for the helpful instructions to get started!

[delucis]

Thanks @connor-baer! Let me know if you have any questions along the way 🙌