backstage: TechDocs returning "ERROR 404: i: Page not found"

Expected Behavior

TechDocs should generate docs properly when opening a docs component from the main menu.

Current Behavior

When opening a Docs site that is configured to use either github or azure devops, you get a 404 error page suggesting that perhaps you are missing an index.md but if you look at the browser console there is a 404 error loading an index.html from an API route. However, there seems to be an issue with the URL itself. Once I change the part of the URL from lower to upper case (“component” to “Component”), everything works fine. Also, when opening techdocs directly from the catalog (https://backstage.xxx.com/catalog/default/component/xxx/docs), it works fine.

Possible Solution

Currently, the following URL is opened after clicking on the techdoc: https://backstage.xxx.com/docs/default/component/xxx

It works after changing the “Component” to upper case: https://backstage.xxx.com/docs/default/Component/xxx

Steps to Reproduce

Generate app using @backstage/create-app @0.3.38
Integrate component with a techdoc from Azure or Github
Open integrated component from the main menu (Docs -> component name)

Context

Error text displayed in UI:

ERROR 404: i: Page not found. This could be because there is no index.md file in the root of the docs directory of this repository.

Looks like someone dropped the mic!
Go back... or please contact support if you think this is a bug.

Your Environment

Docker image based on node:14-buster-slim
App generated using: @backstage/create-app@0.3.38
Edge / Chrome / Firefox

About this issue

Original URL
State: closed
Created 3 years ago
Comments: 16 (15 by maintainers)

Most upvoted comments

@iamEAP i am still getting this same error when creating a new app using the latest version of backstage (1.14.1) which has:

@backstage/plugin-techdocs - 1.6.2
@backstage/plugin-techdocs-backend - 1.6.2

Wondering if anyone else is facing this issue?

regicsolutions on Jun 5, 2023

@camilaibs would you agree? Can we maybe get some support/guidance on this one from the devs?

@nadworny the pull request that fixes this issue is being reviewed to be included in the next Backstage release and a workaround solution has been shared in the discord here.

camilaibs on Aug 30, 2021

Thanks for the patience, all! The latest version of @backstage/create-app should have this fix. If you have an existing deployment of Backstage, you should be able to bump versions and get the fix. Manually updating to the following versions will also work:

@backstage/plugin-techdocs - v0.11.1
@backstage/plugin-techdocs-backend - v0.10.1

iamEAP on Sep 5, 2021

@camilaibs is there a way to be notified when this is going to be included in a stable version of https://www.npmjs.com/package/@backstage/create-app?activeTab=readme?

We always release on Thursdays, it should happen tomorrow and you can subscribe to the next version PR 🙂

camilaibs on Sep 1, 2021

Yes, from my perspective, that means that the issue shall be fixed in code first.

PavelPolyakov on Aug 30, 2021

From my perspective the issue exists, because documentation content is generated in the Component folder. While front-end queries it using components folder. Depending on the OS, probably, back-end code either can or can not find appropriate folder in the local filesystem. In my case we’re using node:14-buster-slim, same happens on macOS, because file system is case sensitive.

PavelPolyakov on Aug 30, 2021