Use this guide for general instructions on using the Sentry SDK with Cloudflare. If you're using any of the listed frameworks, follow their specific setup instructions:

• Astro
• Hono
• Hydrogen
• Next.js
• Nuxt
• Remix
• SvelteKit

Prerequisites

You need:

• A Sentryaccount andproject
• Your application up and running

Step 1: Install

Choose the features you want to configure, and this guide will show you how:

Install the Sentry SDK

Run the command for your preferred package manager to add the Sentry SDK to your application:

npminstall @sentry/cloudflare--save

Step 2: Configure

The main Sentry configuration should happen as early as possible in your app's lifecycle.

Wrangler Configuration

Since the SDK needs access to theAsyncLocalStorage API, you need to set thenodejs_compat compatibility flag in yourwrangler.(jsonc|toml) configuration file:

{  "compatibility_flags": ["nodejs_compat"],}

Release Configuration (Optional)

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

1. TheSENTRY_RELEASE environment variable
2. TheCF_VERSION_METADATA.id binding (if configured)

To enable automatic release detection via Cloudflare's version metadata, add theCF_VERSION_METADATA binding in your wrangler configuration. This provides access to theCloudflare version metadata:

Sentry.withSentry((env)=>({dsn:"___PUBLIC_DSN___",release: env.CF_VERSION_METADATA?.id,}),// ...);

{  // ...  "version_metadata": {    "binding": "CF_VERSION_METADATA"  }}

Setup for Cloudflare Workers

Wrap your worker handler with thewithSentry function, for example, in yourindex.ts file, to initialize the Sentry SDK and hook into the environment:

import*as Sentryfrom"@sentry/cloudflare";exportdefault Sentry.withSentry((env: Env)=>({    dsn:"___PUBLIC_DSN___",// Adds request headers and IP for users, for more info visit:// https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#sendDefaultPii    sendDefaultPii:true,// ___PRODUCT_OPTION_START___ logs// Enable logs to be sent to Sentry    enableLogs:true,// ___PRODUCT_OPTION_END___ logs// ___PRODUCT_OPTION_START___ performance// 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,// ___PRODUCT_OPTION_END___ performance}),{asyncfetch(request, env, ctx){// Your worker logic herereturnnewResponse("Hello World!");},},);

Setup for Cloudflare Pages

To use the Sentry SDK, add thesentryPagesPlugin asmiddleware to your Cloudflare Pages application.

Create a_middleware.js file in yourfunctions directory (Cloudflare Pagesmiddleware). 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:

import*asSentryfrom"@sentry/cloudflare";exportconst onRequest=[// Make sure Sentry is the first middlewareSentry.sentryPagesPlugin((context)=>({dsn:"___PUBLIC_DSN___",// Adds request headers and IP for users, for more info visit:// https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#sendDefaultPiisendDefaultPii:true,// ___PRODUCT_OPTION_START___ logs// Enable logs to be sent to SentryenableLogs:true,// ___PRODUCT_OPTION_END___ logs// ___PRODUCT_OPTION_START___ performance// 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/#tracesSampleRatetracesSampleRate:1.0,// ___PRODUCT_OPTION_END___ performance})),// Add more middlewares here];

// hooks.server.jsimport*asSentryfrom"@sentry/cloudflare";exportconsthandle=({ event, resolve})=>{const requestHandlerOptions={options:{dsn: event.platform.env.SENTRY_DSN,tracesSampleRate:1.0,},request: event.request,context: event.platform.ctx,};returnSentry.wrapRequestHandler(requestHandlerOptions,()=>resolve(event),);};

Step 3: Add Readable Stack Traces With Source Maps (Optional)

The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload yoursource maps to Sentry.

First, set theupload_source_maps option totrue in yourwrangler.(jsonc|toml) config file to enable source map uploading:

{  "upload_source_maps": true,}

Next, run the Sentry Wizard to finish your setup:

npx @sentry/wizard@latest-i sourcemaps

Step 4: Verify Your Setup

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

Issues

First, let's make sure Sentry is correctly capturing errors and creating issues in your project.

Cloudflare Workers

Add the following code snippet to your main worker file to create a/debug-sentry route that triggers an error when called:

exportdefault{asyncfetch(request){const url=newURL(request.url);if(url.pathname==="/debug-sentry"){thrownewError("My first Sentry error!");}// Your existing routes and logic here...returnnewResponse("...");},};

Cloudflare Pages

Create a new route that throws an error when called by adding the following code snippet to a file in yourfunctions directory, such asfunctions/debug-sentry.js:

exportasyncfunctiononRequest(context){thrownewError("My first Sentry error!");}

exportdefault{asyncfetch(request){const url=newURL(request.url);if(url.pathname==="/debug-sentry"){awaitSentry.startSpan({op:"test",name:"My First Test Transaction",},async()=>{awaitnewPromise((resolve)=>setTimeout(resolve,100));// Wait for 100msthrownewError("My first Sentry error!");},);}// Your existing routes and logic here...returnnewResponse("...");},};

exportasyncfunctiononRequest(context){awaitSentry.startSpan({op:"test",name:"My First Test Transaction",},async()=>{awaitnewPromise((resolve)=>setTimeout(resolve,100));// Wait for 100msthrownewError("My first Sentry error!");},);}

View Captured Data in Sentry

Now, head over to your project onSentry.io to view the collected data (it takes a couple of moments for the data to appear).

Known Limitations

Span Durations

Server-side spans will display0ms for their durations. In the Cloudflare Workers runtime,performance.now() andDate.now() only advance after I/O occurs. CPU-bound operations will show zero duration. This is a security measure Cloudflare implements tomitigate against timing attacks.

This is expected behavior in the Cloudflare Workers environment and affects all frameworks deployed to Cloudflare Workers, including Next.js, Astro, Remix, and others.

Next Steps

At this point, you should have integrated Sentry and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

• Explorepractical guides on what to monitor, log, track, and investigate after setup
• Learn how tomanually capture errors
• Continue tocustomize your configuration
• Make use ofCloudflare-specific features
• Get familiar withSentry's product features like tracing, insights, and alerts