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

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"],
}

If you don't set the release option manually, the SDK automatically detects it from these sources (in order of priority):

  1. The SENTRY_RELEASE environment variable
  2. The CF_VERSION_METADATA.id binding (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",
  },
}

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.js
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
];
Don't have access to onRequest?

If you don't have access to the onRequest middleware API, you can use the wrapRequestHandler API instead. For example:

// hooks.server.js
import { wrapRequestHandler } from "@sentry/cloudflare/request";

export const handle = ({ event, resolve }) => {
  const requestHandlerOptions = {
    options: {
      dsn: event.platform.env.SENTRY_DSN,
      tracesSampleRate: 1.0,
    },
    request: event.request,
    context: event.platform.ctx,
  };
  return wrapRequestHandler(requestHandlerOptions, () => resolve(event));
};

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.js
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.js
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.js
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.

Was this helpful?
Help improve this content
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").