fix: Block MDX compilation at Vercel runtime to protect release registry

[codyde]

Summary

This PR blocks MDX compilation from running at Vercel runtime, which was causing:

1. Registry overload: Every runtime MDX compilation fetches from release-registry.services.sentry.io, causing traffic spikes that crashed the registry
2. esbuild errors: Runtime compilation fails with "read-only file system" errors (DOCS-915, 4.9M+ events)

Root Cause Analysis

When users hit URLs that don't exist (404s) or certain edge cases in Next.js routing, the page component tries to render before falling back to not-found. This triggers:

1. getFileBySlugWithCache() is called for a non-existent path
2. Cache check is skipped (only runs when CI env var is set)
3. MDX compilation is attempted via bundleMDX()
4. remarkVariables plugin fetches from release registry
5. esbuild tries to write to /var/task/public/mdx-images (read-only on Lambda)
6. Error is thrown, registry has been hammered

The Fix

Add a guard at the start of getFileBySlug() that throws immediately if we're at Vercel runtime:

const isVercelRuntime = process.env.VERCEL && !process.env.CI && process.env.NODE_ENV !== 'development';

if (isVercelRuntime) {
  throw new Error(`[MDX Runtime Error] Attempted to compile MDX at Vercel runtime for slug "${slug}"...`);
}

Why This Is Safe

• All 9229 docs pages are statically generated during CI builds (force-static + generateStaticParams)
• MDX compilation at runtime was never intended to work - the build dependencies are excluded from the Lambda bundle
• This just makes the failure explicit and fast, protecting the registry
• Local development and CI builds are unaffected

Fixes

• DOCS-915 (4.9M events)
• DOCS-9H5, DOCS-9N0, DOCS-9HB (related ENOENT errors)

[vercel]

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

Project	Deployment	Review	Updated (UTC)
develop-docs	Ready	Preview, Comment	Jan 11, 2026 6:23am
sentry-docs	Ready	Preview, Comment	Jan 11, 2026 6:23am

[sentry]

Bug: Runtime guards added in src/mdx.ts are missing from duplicate functions in src/frontmatter.ts, causing runtime crashes in endpoints that import from the unguarded file.
_{Severity: CRITICAL}

🔍 Detailed Analysis

The pull request introduces runtime guards in src/mdx.ts to prevent MDX compilation on Vercel, but fails to add these same guards to duplicate functions (getDocsFrontMatter, getDevDocsFrontMatter) in src/frontmatter.ts. Two runtime endpoints, app/sitemap.ts and app/api/source-map/route.ts, import these functions from the unguarded src/frontmatter.ts file. As a result, when these endpoints are executed on Vercel, they will still attempt to scan the read-only filesystem, leading to unhandled ENOENT errors and causing the endpoints to crash. This negates the primary goal of the pull request.

💡 Suggested Fix

Apply the same isVercelRuntime guards from src/mdx.ts to the corresponding functions in src/frontmatter.ts. Alternatively, consolidate the duplicate getDocsFrontMatter and getDevDocsFrontMatter functions into a single, guarded implementation to avoid code duplication and ensure consistent behavior.

🤖 Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: src/mdx.ts#L184-L189

Potential issue: The pull request introduces runtime guards in `src/mdx.ts` to prevent
MDX compilation on Vercel, but fails to add these same guards to duplicate functions
(`getDocsFrontMatter`, `getDevDocsFrontMatter`) in `src/frontmatter.ts`. Two runtime
endpoints, `app/sitemap.ts` and `app/api/source-map/route.ts`, import these functions
from the unguarded `src/frontmatter.ts` file. As a result, when these endpoints are
executed on Vercel, they will still attempt to scan the read-only filesystem, leading to
unhandled `ENOENT` errors and causing the endpoints to crash. This negates the primary
goal of the pull request.

_{Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 8440713}

[sentry]

Bug: The app/api/source-map/route.ts endpoint lacks error handling for the new runtime guards, causing an unhandled promise rejection that will crash the API on Vercel.
_{Severity: CRITICAL}

🔍 Detailed Analysis

The new runtime guard added to getDocsFrontMatter and getDevDocsFrontMatter intentionally rejects a promise when executed on Vercel. However, the app/api/source-map/route.ts API route, which calls these functions, does not wrap the call in a try/catch block. Because Next.js API routes execute at runtime, an unhandled promise rejection will occur when this endpoint is accessed on Vercel, causing the API to crash and return a 500 error. While other parts of the code were updated to handle this new error condition, this specific API route was overlooked.

💡 Suggested Fix

Wrap the call to getDevDocsFrontMatter() and getDocsFrontMatter() within the GET handler in app/api/source-map/route.ts with a try/catch block. The catch block should handle the rejected promise gracefully, preventing the API route from crashing, similar to the error handling implemented in src/components/include.tsx.

🤖 Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: src/mdx.ts#L294-L299

Potential issue: The new runtime guard added to `getDocsFrontMatter` and
`getDevDocsFrontMatter` intentionally rejects a promise when executed on Vercel.
However, the `app/api/source-map/route.ts` API route, which calls these functions, does
not wrap the call in a `try/catch` block. Because Next.js API routes execute at runtime,
an unhandled promise rejection will occur when this endpoint is accessed on Vercel,
causing the API to crash and return a 500 error. While other parts of the code were
updated to handle this new error condition, this specific API route was overlooked.

_{Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 8440713}