Improve 404 page for missing rustdoc resources by kivancgnlp · Pull Request #3416 · rust-lang/docs.rs

kivancgnlp · 2026-07-23T12:09:00Z

Summary

Improves the error page shown when a requested rustdoc resource does not exist in an otherwise valid crate version.

Instead of displaying only a generic 404 page, the response now includes links to:

The documentation root for the requested version
The crate page containing all available versions

Fixes #2568.

Changes

Add a contextual ResourceNotFoundInVersion error variant
Preserve /latest/ and pinned-version URLs when constructing recovery links
Render optional recovery links on the HTML error page
Include equivalent links in JSON error responses
Add tests for latest, pinned-version, JSON, and generic 404 behavior
Keep existing no-cache behavior for error responses

Non-goals

This PR intentionally does not:

Redirect missing pages automatically
Search previous versions for the missing resource
Add search integration

These can be considered separately if desired.

Testing

Project compiles locally
Existing direct AxumErrorPage initializers updated
Full test suite pending GitHub Actions

Include an empty `recovery` Vec in the about handler's not-found page response. This ensures the response struct has the newly required `recovery` field and prevents missing-field errors after the page/template was extended.

Refactor JSON error response construction to avoid emitting an empty "links" array. The code now builds a base body with title and message and only inserts the "links" field if recovery links are non-empty. Also minor cleanup: clarified the NoResults comment and added braces around the Redirect match arm.

Refactor the match arm for AxumNope::Redirect in crates/bin/docs_rs_web/src/error.rs to a single-line expression calling redirect_with_policy(target, cache_policy). This is a formatting/clarity change only and does not alter behavior.

syphar

thank you for the work!

only two things, looking at the actual page:

the error message wording can be improved
the styling of the links too

View changes since this review

kivancgnlp · 2026-07-24T11:56:26Z

Thanks @syphar. Agreed.
I’ll simplify the wording and present the recovery links as clearer actions rather than a plain list.

syphar · 2026-07-25T05:30:59Z

Thanks @syphar. Agreed. I’ll simplify the wording and present the recovery links as clearer actions rather than a plain list.

before I spend more time reviewing this:

please remove all claude comments / author from the commit (in the commit message, and the added author).
and most importantly: please confirm that this time you actually manually tested the feature, and believe it's ready for production.

I'm ok with people using AI for their contribution, if the author also reviewed & tested everything.

Address review feedback on rust-lang#2568: clarify the contextual missing-page message and render the recovery links as pure-css action buttons instead of a plain bullet list. JSON error body structure is unchanged.

The error page title lives in a `div.container`, which is only centered on the page when the body sets the `centered` class. The error page doesn't, so the title was centered inside a box pinned to the left edge while the message and recovery links below centered against the full page width. Scope the container centering to the error page with an `error-header` class so the title lines up with the text below it, center the recovery links, and give them a small top gap so they read as part of the message rather than running into it.

kivancgnlp · 2026-07-25T14:01:37Z

I tested the latest branch locally by importing itoa 1.0.18 and opening both contextual 404 routes:

/itoa/latest/itoa/removed_module/index.html

/itoa/1.0.18/itoa/removed_module/index.html

I verified the 404 title and message, responsive button layout, and both recovery-link destinations. I also adjusted the title alignment and spacing after checking the rendered page.

GuillaumeGomez · 2026-07-25T14:08:35Z

Please add a GUI test then. :)

kivancgnlp · 2026-07-25T15:40:22Z

Thanks for the suggestion. I added a GUI test in gui-tests/404.goml covering the contextual 404 title, message, and both recovery links using the existing sysinfo fixture. The GUI test passes locally.

kivancgnlp · 2026-07-28T08:05:42Z

Hi @syphar @GuillaumeGomez. Just checking in. I added the GUI test in gui-tests/404.goml covering the contextual 404 title, message, and both recovery links, and it passes locally.

One note on CI: the "rust linters" job is currently failing, but it looks unrelated to this PR — it's crashing with an internal compiler error while building the tokio dependency (rustc ICE in rustc_codegen_ssa), before it even reaches this crate's code. GUI_test, test, js linters, and both Docker builds are all green. Happy to re-push if a CI re-run doesn't clear it up.

Let me know if there's anything else you'd like adjusted.

syphar · 2026-07-29T09:21:24Z

I'm currently traveling, I can have a look next week.

Yes, the compiler ICE is unrelated to your change. It's fixed in the new nightly compiler.

kivancgnlp added 3 commits July 23, 2026 08:11

fix: improve missing rustdoc page errors

f3b1e4e

Initialize empty recovery in about 404 response

f55bb6f

Include an empty `recovery` Vec in the about handler's not-found page response. This ensures the response struct has the newly required `recovery` field and prevents missing-field errors after the page/template was extended.

Update about.rs

ff88e21

github-actions Bot added the S-waiting-on-review Status: This pull request has been implemented and needs to be reviewed label Jul 23, 2026

kivancgnlp added 3 commits July 23, 2026 15:16

Update about.rs

4099f20

Simplify Redirect match arm formatting

06ada29

Refactor the match arm for AxumNope::Redirect in crates/bin/docs_rs_web/src/error.rs to a single-line expression calling redirect_with_policy(target, cache_policy). This is a formatting/clarity change only and does not alter behavior.

kivancgnlp marked this pull request as ready for review July 23, 2026 13:22

kivancgnlp requested a review from a team as a code owner July 23, 2026 13:22

syphar requested changes Jul 24, 2026

View reviewed changes

kivancgnlp requested a review from syphar July 24, 2026 12:46

improve 404 wording and style recovery links as buttons

2137e12

Address review feedback on rust-lang#2568: clarify the contextual missing-page message and render the recovery links as pure-css action buttons instead of a plain bullet list. JSON error body structure is unchanged.

kivancgnlp force-pushed the fix/contextual-rustdoc-404 branch from 459832c to 2137e12 Compare July 25, 2026 10:03

Add GUI test for contextual 404 page

8f780a1

syphar approved these changes Aug 5, 2026

View reviewed changes

syphar merged commit d794291 into rust-lang:main Aug 5, 2026
15 of 18 checks passed

github-actions Bot added S-waiting-on-deploy This PR is ready to be merged, but is waiting for an admin to have time to deploy it and removed S-waiting-on-review Status: This pull request has been implemented and needs to be reviewed labels Aug 5, 2026

Navigation Menu

Uh oh!

Improve 404 page for missing rustdoc resources - #3416

Improve 404 page for missing rustdoc resources#3416
syphar merged 9 commits into
rust-lang:mainfrom
kivancgnlp:fix/contextual-rustdoc-404

kivancgnlp commented Jul 23, 2026 •

edited

Loading

Uh oh!

syphar left a comment •

edited by rustbot

Loading

Uh oh!

kivancgnlp commented Jul 24, 2026

Uh oh!

syphar commented Jul 25, 2026

Uh oh!

kivancgnlp commented Jul 25, 2026

Uh oh!

GuillaumeGomez commented Jul 25, 2026

Uh oh!

kivancgnlp commented Jul 25, 2026

Uh oh!

kivancgnlp commented Jul 28, 2026

Uh oh!

syphar commented Jul 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

kivancgnlp commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Non-goals

Testing

Uh oh!

syphar left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kivancgnlp commented Jul 24, 2026

Uh oh!

syphar commented Jul 25, 2026

Uh oh!

kivancgnlp commented Jul 25, 2026

Uh oh!

GuillaumeGomez commented Jul 25, 2026

Uh oh!

kivancgnlp commented Jul 25, 2026

Uh oh!

kivancgnlp commented Jul 28, 2026

Uh oh!

syphar commented Jul 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kivancgnlp commented Jul 23, 2026 •

edited

Loading

syphar left a comment •

edited by rustbot

Loading