## TL;DR

Use setAttribute for span metadata instead. v11 changes how spans are collected, what gets collected by default, and which options still exist. Older runtimes cannot run v11. - Self-hosted Sentry 26.4.2 or newer. These no longer work in v11's streaming mode: - beforeSendTransaction and ignoreTransactions: replace with span processors or sampling logic. - sendDefaultPii: replaced by dataCollection.

## When to use

You are seeing this: Treat it as a migration, not a version bump. Use this skill when you run into "Workflow: migrate the JS SDK from v10 to v11".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

Versions mentioned in the source: Node 20.19.0, Sentry 26.4.2. If you are on something much newer or older, the details may have shifted.

v11 changes how spans are collected, what gets collected by default, and which options still exist. Treat it as a migration, not a version bump.

## 1. Check the gates first

- Node 20.19.0 or newer (special minimums apply on Node 22 and 23). Older runtimes cannot run v11.
- Self-hosted Sentry 26.4.2 or newer. Span streaming needs a backend that understands it.
- If either gate fails, stop. Upgrade those first.

## 2. Audit the dead options

These no longer work in v11's streaming mode:

- `beforeSendTransaction` and `ignoreTransactions`: replace with span processors or sampling logic.
- `sendDefaultPii`: replaced by `dataCollection`. Note v11 collects more by default than v10, so review what now flows.

Search the codebase for each before upgrading. Every hit is a behavior change, not just a rename.

## 3. Move span metadata to attributes

Scope tags and extras no longer propagate to spans in stream mode. Use `setAttribute` for span metadata instead. Anything you filter or alert on that was a tag needs migrating, or those alerts go blind.

## 4. Upgrade in stages

1. Staging first, with the full test suite plus synthetic traffic.
2. Compare event volume and content before/after: more data by default means quota impact. Check usage stats, not just functionality.
3. Canary one production service. Watch for the two silent breakages: missing transaction filters and missing span metadata.
4. Roll out fleet-wide.

## 5. Verify the data contract

After each stage, confirm: error events still carry the expected context, spans carry attributes (not tags), sampling behaves as configured, and dashboards/queries built on old tag names are updated or replaced.

## Verify

One production release cycle with no data-contract surprises: volume within expected bounds, all downstream queries and alerts working, and the old v10 options fully removed from the codebase.
