Miranda Limonczenko
86f3a98399
fix(docs): stop reporting guide 404s to Sentry, redirect missing paths ( #50279 )
...
Closes DOCS-1388
## Problem
Expected guide-path 404s were reported to Sentry as errors. They made up
roughly 246k events and nearly all Docs volume, with 0 users impacted.
The cause is a type check that never matched.
`getGuidesMarkdownInternal` tested `error.cause instanceof
FileNotFoundError`, but `GuideModelLoader.fromFs` rethrows
`FileNotFoundError` directly and sets `cause` to the underlying `ENOENT`
error. Every missing guide path fell through to the `else` branch and
hit `Sentry.captureException`.
Nine storage section paths and `database/postgrest` also 404 in
production. They are section `url` values in the nav config with no
landing page and no redirect. They are not reachable from the sidebar,
because a nav item with children renders as an accordion button, so the
traffic is inbound links and crawlers.
## Solution
- Check the error itself as well as its cause, so expected 404s take the
quiet branch.
- Add `ignoreErrors` for `FileNotFound` to `sentry.server.config.ts`,
matching the filtering the client config already does.
- Redirect nine storage section paths to their first child page,
following the existing `storage/cdn` and `storage/uploads` pattern.
- Redirect `database/postgrest` to the Data API guide. The path has no
git history, so its 27k hits are external inbound links.
- Add the missing leading slash to the `storage/access-control`
destination. It resolves correctly today, so this is a cleanup, not a
fix.
## Redirect previews
Redirects are served by the `www` config, so the **Redirect** column
uses the www preview. The www preview cannot render `/docs/**` pages, so
each link lands on a 404 after the hop. That is expected. Check the
`Location` header, or use the **Destination** column to confirm the page
itself.
| Source | Redirect | Destination |
| :--- | :--- | :--- |
| `/docs/guides/storage/production` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/production )
|
[storage/production/scaling](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/production/scaling )
|
| `/docs/guides/storage/security` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/security )
|
[storage/security/ownership](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/security/ownership )
|
| `/docs/guides/storage/serving` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/serving )
|
[storage/serving/downloads](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/serving/downloads )
|
| `/docs/guides/storage/management` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/management )
|
[storage/management/copy-move-objects](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/management/copy-move-objects )
|
| `/docs/guides/storage/s3` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/s3 )
|
[storage/s3/authentication](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/s3/authentication )
|
| `/docs/guides/storage/debugging` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/debugging )
|
[storage/debugging/logs](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/debugging/logs )
|
| `/docs/guides/storage/schema` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/schema )
|
[storage/schema/design](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/schema/design )
|
| `/docs/guides/storage/vector` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/vector )
|
[storage/vector/introduction](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/vector/introduction )
|
| `/docs/guides/storage/analytics/examples` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/analytics/examples )
|
[storage/analytics/examples/duckdb](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/analytics/examples/duckdb )
|
| `/docs/guides/database/postgrest` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/database/postgrest )
|
[api](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/api )
|
| `/docs/guides/storage/access-control` |
[test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/access-control )
|
[storage/security/access-control](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/security/access-control )
|
All eleven return `308` on the www preview with the `Location` shown in
the Destination column. Every destination returns `200`.
## Manual testing
1. Open any **Redirect** link above. The URL changes to the Destination
path, confirming the redirect fires.
2. Open any **Destination** link. The page renders.
3. Confirm the sources 404 on production today, for example
`https://supabase.com/docs/guides/storage/production `.
4. On the [docs
preview](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/schema ),
request a missing guide path and check the deployment logs. The line
reads `Could not read Markdown at path`, not `Error processing Markdown
file at path`. The second form is the branch that calls
`Sentry.captureException`.
2026-09-11 14:05:24 -07:00
Miranda Limonczenko