fix(docs): Handle missing MDX source files correctly in Edge runtime

[sfanahata]

DESCRIBE YOUR PR

This PR fixes an issue where requests for non-existent documentation pages (e.g., /docs/changelog) result in a 500 Internal Server Error instead of a 404 Not Found.

Root Cause

The isExpectedError check in app/[[...path]]/page.tsx used e instanceof Error to identify 'Failed to find a valid source file' errors. In Edge runtime environments, Error objects crossing VM context boundaries cause instanceof Error to return false, preventing the error from being caught and producing a 500 instead of a 404.

Fix

• Extract isExpectedMdxError() into a shared utility (src/mdxErrors.ts) that uses duck-typing (.code property check + message-string fallback) instead of instanceof, which works correctly across Edge runtime VM boundaries.
• Update both catch blocks in page.tsx and the catch block in include.tsx to use the shared function, eliminating code duplication.
• Add diagnostic logging on the re-throw path (temporary, marked with TODO(diagnostic)) to confirm the error shape in production Edge runtime.

Tests Added

• src/mdxErrors.spec.ts: Unit tests for isExpectedMdxError() covering all error shapes: standard Errors, plain objects (Edge runtime simulation), string/null/undefined throws.
• src/mdx.spec.ts: Error contract tests verifying getFileBySlug throws errors with the correct .code property (ENOENT and MDX_RUNTIME_ERROR), and that isExpectedMdxError() recognizes them.

Files Changed

File	Action
src/mdxErrors.ts	New -- shared isExpectedMdxError() function
src/mdxErrors.spec.ts	New -- unit tests (10 test cases)
app/[[...path]]/page.tsx	Edit -- use shared function, add diagnostic logging
src/components/include.tsx	Edit -- use shared function, tighten catch typing
src/mdx.spec.ts	Edit -- add error contract tests (4 test cases)
app/[[...path]]/page.spec.ts	New -- integration tests (8 test cases)

IS YOUR CHANGE URGENT?

• Urgent: This issue has ~400K occurrences and is actively producing 500 errors for users hitting non-existent doc pages.

Fixes DOCS-9WN

PRE-MERGE CHECKLIST

• PR was reviewed and approved by any necessary SMEs
• PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview	Jul 29, 2026 6:24pm
sentry-docs	Ready	Preview	Jul 29, 2026 6:24pm