404 on documentation page for main branch

[DePasqualeOrg]

I get a 404 error for the root of my main branch documentation pages.

However, the latest build results show the docs icon for the main branch, indicating that the build succeeded.

I sometimes also get intermittent "An unknown error occurred" pages, which work on subsequent reloads.

[finestructure]

Hi @DePasqualeOrg , thanks for the report.

That URL you're using isn't quite correct, it should be:

https://swiftpackageindex.com/DePasqualeOrg/swift-mcp/main/documentation

and that URL worked for me when I tested it just now.

Where did you come across it, is it from somewhere on the site?

[DePasqualeOrg]

I'm not sure, but these intermittent 404 errors and "unknown error occurred" pages are a real problem. I think I got a 404 error from a link on my readme, which should work, and then tried to access parent pages.

A separate but related problem is that these parent page URLs do not provide a helpful redirect to the main documentation page.

[DePasqualeOrg]

@finestructure, I am again getting the "Unknown error" pages at https://swiftpackageindex.com/DePasqualeOrg/swift-mcp/main/documentation.

Then, about 5 minutes later, the errors no longer occur.

[DePasqualeOrg]

I looked into this and found a couple things that might help track down the root cause:

• The "An unknown error occurred" message comes from DocC's client-side JavaScript (swift-docc-render), not from the SPI server. When a doc page loads, DocC JS fetches a JSON data file (e.g., /{owner}/{repo}/{ref}/data/documentation/{archive}.json). Its error handling (data.js) shows "page not found" for HTTP 404, but shows "An unknown error occurred" for any other error status. So the server must be returning a non-404 error for a data file request.

• The custom ErrorMiddleware only catches AbortError. Any other error type escapes the middleware, gets converted to a raw 500 by Vapor's internal handler, and is not logged by the application. Broadening the middleware to catch and log all errors would provide visibility into what's intermittently failing.