Docusaurus build fails with "No Docusaurus route context found" for manually created sidebar with many items #10718
Comments
DonaldKellett
added
bug
|
Here's the commit that triggers the bug causing the build to fail: DonaldKellett/docusaurus-10709-repro@2c4431b As can be seen from the commit, adding just a single item to the sidebar anywhere triggers this cryptic build error. The failing job and build logs in CI: https://github.com/DonaldKellett/docusaurus-10709-repro/actions/runs/11983861175/job/33413927236 |
|
Just discovered that the build error disappears when duplicate sub-category names are renamed to become unique, e.g. these 2:
Nevertheless, I insist this is a bug in Docusaurus since the build process should catch duplicated sub-category names in the sidebar if it is not a supported use-case and exit with a human-readable error message instead of exhibiting unspecified behavior and randomly failing builds with a cryptic error message when a certain number of sidebar items is reached. |
|
Sorry for closing your initial issue too eagerly, I didn't know you planned to provide a runnable repro. We usually re-open the issue once a repro is provided. Thanks for the repro, this definitively looks like a bug / DX problem. I suspect both of your categories have the same final URL, and this leads to conflicts/ name collision later in JS modules emitted by Docusaurus. I'll investigate at the end of the week. Until then I'm curious, what is the pathname you access both of these generated index categories? I suspect it's the same pathname, something like:
And you could use the {
type: "category",
label: "Storage",
link: {
type: "generated-index",
title: "Storage",
description: "Articles related to storage on Kubernetes",
slug: "my-kuternete-storage-slug",
},
}I'll still consider it a bug though, because we should prevent these collisions in the first place or at least fail-fast on this case and emit a clear actionable error message for the user. |
slorber
removed
the
status: needs triage
|
Again, maybe not helpful, but we are also experiencing a similar issue where 3.6+ versions are throwing lots of missing context errors in custom sidebars during prod compilation (I think dev works? And I think 3.6.3 was triggering it for us; or some pseudo randomness?). I have not debugged our setup or checked for collisions like mentioned above, but wanted to add that I think this is a more broad current pain point potentially. |
Thanks! I believe the generated pathname for both subcategories is indeed While our team fixed the build by re-assigning unique names, e.g. "Kubernetes Storage" vs. "OpenShift Storage", may I ask what the optional |
|
The bug being reported here is likely a historical one, not related to a recent release. I don't see any recent change that could lead to that kind of error in v3.6+ (apart from the opt-in Docusaurus Faster flags maybe). Please try to be sure. Because we can't do much with a vague comment like that 😅. We need runnable bug repros, a precise bug description, with exact version numbers that succeed or break your app. It's possible that the bug feels "random" because it might be sensitive to the order in which Docusaurus emit modules, and Docusaurus runs code in parallel. Maybe your app still works if module A overrides module B, and only fails if module B overrides module A. |
|
Damn, this was not easy to troubleshoot. Many little things could "fix" the problem but it wasn't clear why, and what's the best fix for it. This is really bad luck, you had 1/1000 chance for encountering a hash collision in our route chunks codename generation. 2 route definitions with the same path lead to the exact same hash: CONFLICT /internal/technical-kb/docs-456 {
plugin: { name: 'docusaurus-plugin-content-docs', id: 'default' },
path: '/internal/technical-kb/docs',
exact: false,
component: '@theme/DocsRoot',
routes: [
{
path: '/internal/technical-kb/docs',
exact: false,
component: '@theme/DocVersionRoot',
routes: [Array],
props: undefined,
priority: -1,
modules: [Object]
}
],
context: {
plugin: '@generated/docusaurus-plugin-content-docs/default/__plugin.json'
},
modules: {},
props: undefined
}
CONFLICT /internal/technical-kb/docs-456 {
path: '/internal/technical-kb/docs',
exact: false,
component: '@theme/DocVersionRoot',
routes: [
{
path: '/internal/technical-kb/docs',
exact: false,
component: '@theme/DocRoot',
routes: [Array],
modules: {},
props: undefined
}
],
props: undefined,
priority: -1,
modules: {
__props: '@generated/docusaurus-plugin-content-docs/default/p/internal-technical-kb-docs-462.json'
}
}This leads Instead of this: Note that 2 routes with the same path are normal/expected, it's how we handle the docs routing tree: {
path: "/docs",
component: "@theme/DocsRoot",
routes: [
{
path: "/docs",
component: "@theme/DocVersionRoot"
routes: []
}
]
}Here what happens in practice is that the parent route has the exact same hash as its child 😅 and this leads to a hash collision because we generate unique keys using |
|
Will be fixed in the next release with #10727 Note that in your case, the issue is only temporary. Editing many things on your site will trigger new hashes to be computed, and the collision will not be there anymore. Just editing any sidebar item or category label fixes the collision for example. |
Have you read the Contributing Guidelines on issues?
Prerequisites
npm run clearoryarn clearcommand.rm -rf node_modules yarn.lock package-lock.jsonand re-installing packages.Description
This is a duplicate of #10709 which was closed due to lacking a reproducible example. So here's a reproducible example: https://github.com/DonaldKellett/docusaurus-10709-repro
Building our production Technical KB written in Docusaurus with
npm run buildrecently failed consistently with the error message below.The problem is reproducible in that the error appears 100% of the time when we try to add just 1 more item to our manually created sidebar (maybe our sidebar is too large?) regardless of what the item is or where it is placed within the sidebar, but our Docusaurus site contains sensitive and confidential information so we can't share the source code here. Nevertheless, we'll try to include as much relevant information as possible to help reproduce the issue without divulging too many details.
Reproducible demo
https://github.com/DonaldKellett/docusaurus-10709-repro
Steps to reproduce
Without divulging too many details, we're using Docusaurus v3.6.1 with the
@docusaurus/fasterplugin enabled though we found that the issue persists regardless of whether the experimental plugin is enabled or disabled.Our
package.jsonandpackage-lock.jsonfiles are as attached. In particular, the version ofp-mapused as seen inpackage-lock.jsonis4.0.0which is important as we will see later:The issue is consistently triggered when we try to add 1 more item anywhere within our manually created sidebar in
sidebars.js. Here's an overview of what it looks like:For reference, here's what our
docusaurus.config.jslooks like (portions omitted due to containing sensitive information):Expected behavior
Building the site with
npm run buildfinishes without issues. The site loads and displays correctly withnpm run serve.Actual behavior
Docusaurus static site generation failed for 306 paths:
The detailed error for each failure is "Error: Unexpected: no Docusaurus route context found" which can be traced down to
p-map/index.js:57:22and is identical for each failure.The offending line in version
4.0.0ofp-mapis: https://github.com/sindresorhus/p-map/blob/a4b4dec459544d98880bc53a580e53691aff9fa9/index.js#L57Screenshots containing the error messages in our failing GitLab CI builds are attached below.
Your environment
v22.11.0Self-service
The text was updated successfully, but these errors were encountered: