From 9c1f90d7e8bbb54f589e6be1d1991f28218c38eb Mon Sep 17 00:00:00 2001
From: JPeer264 <jan.peer@sentry.io>
Date: Tue, 5 May 2026 14:21:42 +0200
Subject: [PATCH] docs(cloudflare): Add waitUntil limitation

---
 .../javascript/guides/cloudflare/index.mdx    | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx
index 4bfb956d37296..e5c93d48f6f40 100644
--- a/docs/platforms/javascript/guides/cloudflare/index.mdx
+++ b/docs/platforms/javascript/guides/cloudflare/index.mdx
@@ -223,6 +223,40 @@ Server-side spans will display `0ms` for their durations. In the Cloudflare Work
 
 This is expected behavior in the Cloudflare Workers environment and affects all frameworks deployed to Cloudflare Workers, including Next.js, Astro, Remix, and others.
 
+### Missing Spans in `waitUntil()`
+
+If you're using Cloudflare's [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil) to run background tasks and spans created inside `waitUntil()` are not showing up in Sentry, this is because the request's root span has already ended by the time the background work runs.
+
+To capture spans inside `waitUntil()`, wrap your deferred work with `startSpan` and set `forceTransaction: true`. This creates a separate transaction for the background work:
+
+```javascript {filename:index.js}
+import * as Sentry from "@sentry/cloudflare";
+
+export default {
+  async fetch(request, env, ctx) {
+    // Main request handling
+    const response = processRequest(request);
+
+    // Background work with proper tracing
+    ctx.waitUntil(
+      Sentry.startSpan(
+        { name: "background.task", op: "task", forceTransaction: true },
+        () => updateCacheAndDatabase()
+      )
+    );
+
+    return response;
+  },
+};
+
+async function updateCacheAndDatabase() {
+  // Database operations
+  // Any spans created here will be captured
+}
+```
+
+The `forceTransaction: true` option is required because it creates a separate transaction for the `waitUntil()` work. Without it, spans created after the request ends might get lost.
+
 ## Next Steps
 
 At this point, you should have integrated Sentry and should already be sending data to your Sentry project.