Cloudflare Pages
Learn how to instrument a Cloudflare Pages application with Sentry using the sentryPagesPlugin middleware.
Cloudflare recommends migrating to Workers with static assets. Workers covers most Pages use cases with a broader feature set, and it's where new Cloudflare features land. Existing Pages projects will continue to work, so the guidance on this page remains accurate. For new projects, however, use Workers and follow the Cloudflare guide instead.
After migrating, use the Vite plugin or withSentry instead of sentryPagesPlugin, depending on your build setup.
Cloudflare Pages applications are instrumented with the sentryPagesPlugin middleware instead of the withSentry wrapper that Workers use. The rest of the SDK behaves the same, so the Cloudflare guide still applies for installation, Wrangler configuration, source maps, and the options reference.
npm install @sentry/cloudflare --save
npm install @sentry/cloudflare --save
yarn add @sentry/cloudflare
pnpm add @sentry/cloudflare
Since the SDK needs access to the AsyncLocalStorage API, you need to set the nodejs_compat compatibility flag and a compatibility_date of 2024-09-23 or later in your wrangler.(jsonc|toml) configuration file. We recommend the latest compatibility date, as some integrations depend on newer Cloudflare runtime features:
wrangler.jsonc{
// Set this to today's date
"compatibility_date": "2026-11-18",
"compatibility_flags": ["nodejs_compat"],
}
{
// Set this to today's date
"compatibility_date": "2026-11-18",
"compatibility_flags": ["nodejs_compat"],
}
# Set this to today's date
compatibility_date = "2026-11-18"
compatibility_flags = ["nodejs_compat"]
If you don't set the release option manually, the SDK automatically detects it from these sources (in order of priority):
- The
SENTRY_RELEASEenvironment variable - The
CF_VERSION_METADATA.idbinding (if configured)
To enable automatic release detection via Cloudflare's version metadata, add the CF_VERSION_METADATA binding in your wrangler configuration. This provides access to the Cloudflare version metadata.
wrangler.jsonc{
// ...
"version_metadata": {
"binding": "CF_VERSION_METADATA",
},
}
{
// ...
"version_metadata": {
"binding": "CF_VERSION_METADATA",
},
}
[version_metadata]
binding = "CF_VERSION_METADATA"
To use the Sentry SDK, add the sentryPagesPlugin as middleware to your Cloudflare Pages application.
Create a _middleware.js file in your functions directory (Cloudflare Pages middleware). Create the directory in the root of your project if it doesn't already exist, then create the file and import and initialize the Sentry Cloudflare SDK:
functions/_middleware.jsimport * as Sentry from "@sentry/cloudflare";
export const onRequest = [
// Make sure Sentry is the first middleware
Sentry.sentryPagesPlugin((context) => ({
dsn: "___PUBLIC_DSN___",
// Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
// Learn more at
// https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#tracesSampleRate
tracesSampleRate: 1.0,
})),
// Add more middlewares here
];
import * as Sentry from "@sentry/cloudflare";
export const onRequest = [
// Make sure Sentry is the first middleware
Sentry.sentryPagesPlugin((context) => ({
dsn: "___PUBLIC_DSN___",
// Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
// Learn more at
// https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#tracesSampleRate
tracesSampleRate: 1.0,
})),
// Add more middlewares here
];
By default, the SDK sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. The SDK always filters sensitive values whose keys match a built-in denylist, such as auth or password, and sends [Filtered] instead.
To send less data, turn off the categories you don't need in the dataCollection option:
functions/_middleware.jsexport const onRequest = [
Sentry.sentryPagesPlugin((context) => ({
dsn: "___PUBLIC_DSN___",
dataCollection: {
userInfo: false,
// other categories
},
})),
];
export const onRequest = [
Sentry.sentryPagesPlugin((context) => ({
dsn: "___PUBLIC_DSN___",
dataCollection: {
userInfo: false,
// other categories
},
})),
];
For the full list of categories and their defaults, see the dataCollection options.
Create a new route that throws an error when called by adding the following code snippet to a file in your functions directory, such as functions/debug-sentry.js:
debug-sentry.jsexport async function onRequest(context) {
throw new Error("My first Sentry error!");
}
export async function onRequest(context) {
throw new Error("My first Sentry error!");
}
To test your tracing configuration, start a span around the failing code:
debug-sentry.jsimport * as Sentry from "@sentry/cloudflare";
export async function onRequest(context) {
await Sentry.startSpan(
{
op: "test",
name: "My First Test Span",
},
async () => {
await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms
throw new Error("My first Sentry error!");
},
);
}
import * as Sentry from "@sentry/cloudflare";
export async function onRequest(context) {
await Sentry.startSpan(
{
op: "test",
name: "My First Test Span",
},
async () => {
await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms
throw new Error("My first Sentry error!");
},
);
}
Then head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).
The limitations of the Cloudflare Workers runtime apply to Pages Functions as well, including zero-duration spans for CPU-bound work.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").