feat(cloudflare): Only capture workflow step error on final retry attempt (#21025)

closes #17421
closes
[JS-869](https://linear.app/getsentry/issue/JS-869/cloudflare-workflow-option-to-have-only-one-error-on-step-failure)

Cloudflare Workflows (wrangler 4.86.0+) now pass step context with
`attempt` and `config.retries.limit` to step callbacks. When available,
we use this to only capture errors on the final retry attempt, avoiding
duplicate error events during retries.

For older wrangler versions without step context, the SDK falls back to
legacy behavior (capturing errors on every attempt).

- Add integration tests for step context behavior
  - This is specifically for the new behavior
- Add e2e test for legacy behavior (wrangler 4.70.0)
  - This makes sure we won't break older wrangler versions
- This test breaks when wrangler is updated, as with a newer wrangler
version you get a higher compat version, therefore you get only 1 error
instead of 3
- A E2E test was chosen as it seem the `compatibility_date` has no
effect with `wrangler`, so I couldn't make an integration test

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: JPeer264

dev-packages/cloudflare-integration-tests/package.json

@@ -19,11 +19,11 @@
     "hono": "^4.12.18"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250922.0",
+    "@cloudflare/workers-types": "^4.20260426.0",
     "@sentry-internal/test-utils": "10.55.0",
     "eslint-plugin-regexp": "^1.15.0",
     "vitest": "^3.2.4",
-    "wrangler": "4.61.0"
+    "wrangler": "4.86.0"
   },
   "volta": {
     "extends": "../../package.json"

dev-packages/cloudflare-integration-tests/suites/tracing/workflow/test.ts

@@ -29,6 +29,7 @@ it('Workflow steps create transactions with correct attributes', async ({ signal
                 [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.faas.cloudflare.workflow',
                 [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'task',
                 [SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE]: 1,
+                'cloudflare.workflow.attempt': 1,
               },
             },
           }),
@@ -55,6 +56,7 @@ it('Workflow steps create transactions with correct attributes', async ({ signal
                 [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.faas.cloudflare.workflow',
                 [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'task',
                 [SEMANTIC_ATTRIBUTE_SENTRY_SAMPLE_RATE]: 1,
+                'cloudflare.workflow.attempt': 1,
               },
             },
           }),

dev-packages/cloudflare-integration-tests/suites/workflows/step-context/index.ts

@@ -0,0 +1,107 @@
+import * as Sentry from '@sentry/cloudflare';
+import { WorkflowEntrypoint } from 'cloudflare:workers';
+import type { WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
+
+interface Env {
+  SENTRY_DSN: string;
+  STEP_CONTEXT_WORKFLOW: Workflow;
+}
+
+interface WorkflowParams {
+  failCount: number;
+  captureManual?: boolean;
+}
+class StepContextTestWorkflowBase extends WorkflowEntrypoint<Env, WorkflowParams> {
+  async run(event: WorkflowEvent<WorkflowParams>, step: WorkflowStep): Promise<void> {
+    let remainingFailures = event.payload.failCount;
+
+    const result = await step.do(
+      'failing-step',
+      {
+        retries: {
+          limit: 2,
+          delay: 100,
+        },
+      },
+      async ctx => {
+        if (event.payload.captureManual) {
+          Sentry.captureException(new Error(`Manual capture on attempt ${ctx.attempt}`));
+        }
+
+        if (remainingFailures > 0) {
+          remainingFailures--;
+          throw new Error('Intentional failure for retry test');
+        }
+      },
+    );
+
+    return result;
+  }
+}
+
+export const StepContextTestWorkflow = Sentry.instrumentWorkflowWithSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+  }),
+  StepContextTestWorkflowBase,
+);
+
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+  }),
+  {
+    async fetch(request, env, _ctx) {
+      const url = new URL(request.url);
+
+      if (url.pathname === '/trigger-workflow') {
+        const failCount = parseInt(url.searchParams.get('failCount') || '0', 10);
+        const captureManual = url.searchParams.get('captureManual') === 'true';
+
+        try {
+          const instance = await env.STEP_CONTEXT_WORKFLOW.create({
+            params: { failCount, captureManual },
+          });
+
+          return new Response(JSON.stringify({ id: instance.id }), { headers: { 'Content-Type': 'application/json' } });
+        } catch (e) {
+          return new Response(JSON.stringify({ error: 'Failed to create workflow', details: String(e) }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          });
+        }
+      }
+
+      if (url.pathname === '/flush-marker') {
+        Sentry.captureMessage('flush-marker');
+        return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+      }
+
+      const statusMatch = url.pathname.match(/^\/workflow-status\/(.+)$/);
+
+      if (statusMatch) {
+        const workflowId = statusMatch[1];
+
+        try {
+          const instance = await env.STEP_CONTEXT_WORKFLOW.get(workflowId!);
+          const status = await instance.status();
+
+          return new Response(
+            JSON.stringify({
+              id: workflowId,
+              status,
+            }),
+            { headers: { 'Content-Type': 'application/json' } },
+          );
+        } catch (e) {
+          return new Response(JSON.stringify({ error: 'Failed to get workflow status', details: String(e) }), {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' },
+          });
+        }
+      }
+
+      return new Response('Step Context Test Worker');
+    },
+  } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/workflows/step-context/test.ts

@@ -0,0 +1,109 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { createRunner } from '../../../runner';
+
+interface TriggerResponse {
+  id: string;
+}
+
+interface StatusResponse {
+  id: string;
+  status: { status: string };
+}
+
+async function waitForWorkflowStatus(
+  makeRequest: <T>(method: 'get' | 'post', path: string) => Promise<T | undefined>,
+  workflowId: string,
+): Promise<StatusResponse | undefined> {
+  for (let i = 0; i < 30; i++) {
+    const status = await makeRequest<StatusResponse>('get', `/workflow-status/${workflowId}`);
+    if (status?.status?.status === 'errored' || status?.status?.status === 'complete') {
+      return status;
+    }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  return undefined;
+}
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+  const [, items] = envelope;
+  const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+  expect(itemHeader.type).toBe('event');
+  expect(itemBody.message).toBe('flush-marker');
+};
+
+it('With step context, only one error is captured on final retry attempt', async ({ signal }) => {
+  const runner = createRunner(__dirname)
+    .expect((envelope: Envelope): void => {
+      const [, items] = envelope;
+      const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+      expect(itemHeader.type).toBe('event');
+      expect(itemBody.exception).toBeDefined();
+
+      const exception = itemBody.exception as { values?: Array<{ value?: string }> };
+      expect(exception?.values?.[0]?.value).toBe('Intentional failure for retry test');
+    })
+    .expect(flushMarkerMatcher)
+    .start(signal);
+
+  const trigger = await runner.makeRequest<TriggerResponse>('get', '/trigger-workflow?failCount=3');
+
+  expect(trigger?.id).toBeDefined();
+
+  const status = await waitForWorkflowStatus(runner.makeRequest.bind(runner), trigger!.id);
+  expect(status?.status?.status).toBe('errored');
+
+  await runner.makeRequest('get', '/flush-marker');
+  await runner.completed();
+});
+
+it('No error event when step eventually succeeds within retry limit', async ({ signal }) => {
+  const runner = createRunner(__dirname).expect(flushMarkerMatcher).start(signal);
+
+  const trigger = await runner.makeRequest<TriggerResponse>('get', '/trigger-workflow?failCount=1');
+  expect(trigger?.id).toBeDefined();
+
+  const status = await waitForWorkflowStatus(runner.makeRequest.bind(runner), trigger!.id);
+  expect(status?.status?.status).toBe('complete');
+
+  await runner.makeRequest('get', '/flush-marker');
+  await runner.completed();
+});
+
+it('Manually captured exceptions are always sent on every attempt', async ({ signal }) => {
+  const runner = createRunner(__dirname)
+    .expectN(3, (envelope: Envelope): void => {
+      const [, items] = envelope;
+      const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+      expect(itemHeader.type).toBe('event');
+      expect(itemBody.exception).toBeDefined();
+
+      const exception = itemBody.exception as { values?: Array<{ value?: string }> };
+      expect(exception?.values?.[0]?.value).toMatch(/^Manual capture on attempt \d+$/);
+    })
+    .expect((envelope: Envelope): void => {
+      const [, items] = envelope;
+      const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+      expect(itemHeader.type).toBe('event');
+      expect(itemBody.exception).toBeDefined();
+
+      const exception = itemBody.exception as { values?: Array<{ value?: string }> };
+      expect(exception?.values?.[0]?.value).toBe('Intentional failure for retry test');
+    })
+    .expect(flushMarkerMatcher)
+    .unordered()
+    .start(signal);
+
+  const trigger = await runner.makeRequest<TriggerResponse>('get', '/trigger-workflow?failCount=3&captureManual=true');
+  expect(trigger?.id).toBeDefined();
+
+  const status = await waitForWorkflowStatus(runner.makeRequest.bind(runner), trigger!.id);
+  expect(status?.status?.status).toBe('errored');
+
+  await runner.makeRequest('get', '/flush-marker');
+  await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/workflows/step-context/wrangler.jsonc

@@ -0,0 +1,13 @@
+{
+  "name": "workflow-step-context-test",
+  "compatibility_date": "2026-05-01",
+  "main": "index.ts",
+  "compatibility_flags": ["nodejs_compat"],
+  "workflows": [
+    {
+      "name": "step-context-test-workflow",
+      "binding": "STEP_CONTEXT_WORKFLOW",
+      "class_name": "StepContextTestWorkflow",
+    },
+  ],
+}

dev-packages/e2e-tests/test-applications/cloudflare-workers-workflow-legacy/.gitignore

@@ -0,0 +1 @@
+.wrangler

dev-packages/e2e-tests/test-applications/cloudflare-workers-workflow-legacy/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "cloudflare-workers-workflow-legacy",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "wrangler dev --var \"E2E_TEST_DSN:$E2E_TEST_DSN\" --log-level=$(test $CI && echo 'none' || echo 'log')",
+    "build": "wrangler deploy --dry-run",
+    "typecheck": "tsc --noEmit",
+    "test:build": "pnpm install && pnpm build",
+    "test:assert": "pnpm typecheck && pnpm test:dev",
+    "test:dev": "TEST_ENV=development playwright test"
+  },
+  "dependencies": {
+    "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz"
+  },
+  "devDependencies": {
+    "@playwright/test": "~1.56.0",
+    "@cloudflare/workers-types": "^4.20260303.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils",
+    "typescript": "^5.5.2",
+    "wrangler": "4.70.0"
+  },
+  "volta": {
+    "node": "24.15.0",
+    "extends": "../../package.json"
+  }
+}

dev-packages/e2e-tests/test-applications/cloudflare-workers-workflow-legacy/playwright.config.ts

@@ -0,0 +1,9 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const config = getPlaywrightConfig({
+  startCommand: 'pnpm dev',
+  port: 8787,
+  eventProxyFile: 'start-event-proxy.mjs',
+});
+
+export default config;

dev-packages/e2e-tests/test-applications/cloudflare-workers-workflow-legacy/src/index.ts

@@ -0,0 +1,91 @@
+import * as Sentry from '@sentry/cloudflare';
+import { WorkflowEntrypoint } from 'cloudflare:workers';
+import type { WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
+
+interface Env {
+  E2E_TEST_DSN: string;
+  RETRY_WORKFLOW: Workflow;
+}
+
+interface WorkflowParams {
+  failCount: number;
+}
+
+class RetryTestWorkflowBase extends WorkflowEntrypoint<Env, WorkflowParams> {
+  async run(event: WorkflowEvent<WorkflowParams>, step: WorkflowStep): Promise<string> {
+    let remainingFailures = event.payload.failCount;
+
+    await step.do(
+      'failing-step',
+      {
+        retries: {
+          limit: 2,
+          delay: 100,
+        },
+      },
+      async () => {
+        if (remainingFailures > 0) {
+          remainingFailures--;
+          throw new Error('Intentional failure for retry test');
+        }
+        return 'success';
+      },
+    );
+
+    return 'workflow completed';
+  }
+}
+
+export const RetryTestWorkflow = Sentry.instrumentWorkflowWithSentry(
+  (env: Env) => ({
+    dsn: env.E2E_TEST_DSN,
+    tunnel: 'http://localhost:3031/',
+  }),
+  RetryTestWorkflowBase,
+);
+
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.E2E_TEST_DSN,
+    tunnel: 'http://localhost:3031/',
+  }),
+  {
+    async fetch(request, env, _ctx) {
+      const url = new URL(request.url);
+
+      if (url.pathname === '/flush-marker') {
+        Sentry.captureMessage('flush-marker');
+        return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+      }
+
+      if (url.pathname === '/trigger-workflow') {
+        const failCount = parseInt(url.searchParams.get('failCount') || '3', 10);
+
+        const instance = await env.RETRY_WORKFLOW.create({
+          params: { failCount },
+        });
+
+        // Poll for workflow completion
+        for (let i = 0; i < 30; i++) {
+          try {
+            const status = await instance.status();
+            if (status.status === 'complete' || status.status === 'errored') {
+              return new Response(JSON.stringify({ id: instance.id, status }), {
+                headers: { 'Content-Type': 'application/json' },
+              });
+            }
+          } catch {
+            // status() may not be available yet
+          }
+          await new Promise(r => setTimeout(r, 500));
+        }
+
+        return new Response(JSON.stringify({ id: instance.id, status: 'timeout' }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      return new Response('Workflow Legacy Test Worker');
+    },
+  } satisfies ExportedHandler<Env>,
+);