Sentry Upgrade Migration

Detect installed Sentry SDK versions, identify breaking API changes, apply automated codemods, and verify the upgrade succeeds with test events and traces.

Current State

!

npm list 2>/dev/null | command grep @sentry || echo 'No npm Sentry packages found'

pip show sentry-sdk 2>/dev/null | command grep -E '^(Name|Version)' || echo 'No Python sentry-sdk found'

node --version 2>/dev/null || echo 'Node.js not available'

Overview

Sentry SDK upgrades require careful handling of breaking API changes. The v7 to v8 JavaScript migration is the most impactful, removing the Hub pattern, replacing Transaction/Span APIs with

startSpan()

configure_scope()

get_current_scope()

@sentry/migr8

Prerequisites

• Current Sentry SDK version identified (run DCI above)
• Target version changelog reviewed
• Non-production environment for testing upgrades
• All

  @sentry/*

  packages at the same major version before starting
• Node.js >= 18.19.0 or >= 20.6.0 for SDK v8 (ESM support required)

Instructions

Step 1. Identify Current SDK Version and Scan for Deprecated APIs

# JavaScript: list all Sentry packages and their versions
npm ls 2>/dev/null | command grep "@sentry/"

# Python: check installed version
pip show sentry-sdk 2>/dev/null

# Verify all @sentry/* packages are the same major version (critical!)
# Mixed versions cause runtime crashes
npm ls @sentry/core @sentry/node @sentry/browser @sentry/utils 2>/dev/null

Scan the codebase for deprecated patterns that need migration:

# Detect v7 Hub usage (removed in v8)
command grep -rn "getCurrentHub\|configureScope\|hub\.capture" src/ --include="*.ts" --include="*.js"

# Detect v7 Transaction API (replaced in v8)
command grep -rn "startTransaction\|\.startChild\|\.finish()" src/ --include="*.ts" --include="*.js"

# Detect class-based integrations (replaced in v8)
command grep -rn "new Sentry\.\|new BrowserTracing\|new Integrations\." src/ --include="*.ts" --include="*.js"

# Detect @sentry/tracing imports (package removed in v8)
command grep -rn "from '@sentry/tracing'" src/ --include="*.ts" --include="*.js"

# Python: detect v1 scope API (replaced in v2)
command grep -rn "configure_scope\|push_scope" src/ --include="*.py"

Step 2. Run the Automated Migration Codemod (JavaScript v7 to v8)

# First upgrade to latest v7 to get deprecation warnings
npm install @sentry/node@7

# Run the official migr8 codemod — rewrites deprecated APIs automatically
npx @sentry/migr8@latest
# Handles: Hub removal, integration class→function, import path changes
# Does NOT handle: Transaction→startSpan, ESM init pattern, custom transports

# Now upgrade to v8
npm install @sentry/node@8

Step 3. Apply Breaking Change Fixes the Codemod Misses

Breaking Change: Transaction/Span API replaced with

startSpan()

// v7 (OLD) — manual transaction lifecycle
const transaction = Sentry.startTransaction({ name: 'process', op: 'task' });
const span = transaction.startChild({ op: 'db.query', description: 'SELECT users' });
// ... do work
span.finish();
transaction.finish();

// v8 (NEW) — callback-based, auto-finishes on return
await Sentry.startSpan({ name: 'process', op: 'task' }, async () => {
  await Sentry.startSpan({ name: 'SELECT users', op: 'db.query' }, async () => {
    // ... do work
  }); // span auto-finishes when callback returns
}); // root span auto-finishes when callback returns

Breaking Change: Hub removed, use Scope API

// v7 (OLD)
const hub = Sentry.getCurrentHub();
hub.configureScope((scope) => {
  scope.setTag('region', 'us-east-1');
});
const transaction = hub.startTransaction({ name: 'my-tx' });

// v8 (NEW)
Sentry.withScope((scope) => {
  scope.setTag('region', 'us-east-1');
});
Sentry.startSpan({ name: 'my-tx', op: 'custom' }, (span) => {
  // work within span
});

Breaking Change: Integrations are functions, not classes

// v7 (OLD)
import * as Sentry from '@sentry/node';
Sentry.init({
  integrations: [new Sentry.Integrations.Http({ tracing: true })],
});

// v8 (NEW) — most integrations are auto-enabled
Sentry.init({
  integrations: [
    Sentry.httpIntegration({ tracing: true }),
  ],
});

Breaking Change:

@sentry/tracing

// v7 (OLD)
import { BrowserTracing } from '@sentry/tracing';
Sentry.init({
  integrations: [new BrowserTracing()],
});

// v8 (NEW) — built into @sentry/browser and @sentry/node
Sentry.init({
  integrations: [
    Sentry.browserTracingIntegration(),
  ],
});

Breaking Change: ESM initialization requires separate file

// v7 (OLD) — init at top of entry file
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '...' });
// ... app code

// v8 (NEW) — must be in separate file, loaded via --import
// instrument.mjs (separate file)
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '...' });

// Run with: node --import ./instrument.mjs app.mjs
// Or in package.json: "start": "node --import ./instrument.mjs app.mjs"

Breaking Change: Custom transport must return response

// v7 (OLD) — send could return void
makeRequest(request) {
  sendToBackend(request);
}

// v8 (NEW) — must return TransportMakeRequestResponse
makeRequest(request) {
  sendToBackend(request);
  return { statusCode: 200 };
}

See major-version-migrations.md for v6-to-v7 and Python v1-to-v2 migration details.

Step 4. Python SDK v1 to v2 Migration

# v1 (OLD) — configure_scope / push_scope
import sentry_sdk

with sentry_sdk.configure_scope() as scope:
    scope.set_tag("key", "value")

with sentry_sdk.push_scope() as scope:
    scope.set_extra("debug_info", data)
    sentry_sdk.capture_message("scoped message")

# v2 (NEW) — get_current_scope / new_scope
import sentry_sdk

scope = sentry_sdk.get_current_scope()
scope.set_tag("key", "value")

with sentry_sdk.new_scope() as scope:
    scope.set_extra("debug_info", data)
    sentry_sdk.capture_message("scoped message")

# Upgrade Python SDK
pip install --upgrade sentry-sdk

# Verify version
python -c "import sentry_sdk; print(sentry_sdk.VERSION)"

Step 5. Align All Package Versions and Update Bundler Plugins

# All @sentry/* packages MUST be the same major version
# Mixed versions cause "Cannot read properties of undefined" runtime errors
npm install @sentry/node@8 @sentry/browser@8 @sentry/react@8 @sentry/profiling-node@8

# Remove deprecated packages
npm uninstall @sentry/tracing @sentry/hub 2>/dev/null

# Update bundler plugins (must be v2.14.2+ for SDK v8 compatibility)
npm install @sentry/webpack-plugin@latest @sentry/vite-plugin@latest 2>/dev/null

Step 6. Verify the Upgrade with Test Events

// test-migration.mjs — run after upgrading
import * as Sentry from '@sentry/node';

async function verifyUpgrade() {
  console.log('SDK Version:', Sentry.SDK_VERSION);

  // 1. Test error capture
  try {
    throw new Error('Migration verification error');
  } catch (e) {
    const eventId = Sentry.captureException(e);
    console.log('Error captured:', eventId ? 'PASS' : 'FAIL');
  }

  // 2. Test scoped context (v8 API)
  Sentry.withScope((scope) => {
    scope.setTag('test', 'migration-verify');
    scope.setUser({ id: 'test-user' });
    Sentry.captureMessage('Scoped context test');
  });
  console.log('Scoped context: PASS');

  // 3. Test performance span (v8 API — replaces startTransaction)
  await Sentry.startSpan(
    { name: 'migration-verify', op: 'test' },
    async (span) => {
      await Sentry.startSpan(
        { name: 'child-operation', op: 'test.child' },
        async () => {
          await new Promise((r) => setTimeout(r, 50));
        }
      );
      console.log('Span created:', span ? 'PASS' : 'FAIL');
    }
  );

  // 4. Test breadcrumbs
  Sentry.addBreadcrumb({
    category: 'test',
    message: 'Migration breadcrumb',
    level: 'info',
  });
  console.log('Breadcrumb: PASS');

  // 5. Flush and verify delivery
  const flushed = await Sentry.flush(5000);
  console.log('Flush:', flushed ? 'PASS' : 'FAIL');
}

verifyUpgrade();

See testing-after-upgrade.md for the full verification checklist.

Step 7. Gradual Rollout Strategy

1. Upgrade in development environment, run full test suite
2. Watch for

   Sentry.startTransaction is not a function

   or similar runtime errors
3. Deploy to staging, monitor Sentry dashboard for 1-2 days
4. Check source maps still resolve (re-upload if bundler plugin changed)
5. Verify trace propagation between services (check

   sentry-trace

   header)
6. Deploy to production with rollback plan ready

Output

• SDK upgraded to target version with all

  @sentry/*

  packages aligned
• Deprecated APIs migrated: Hub removed, Transaction replaced with

  startSpan()

  , integrations converted to functions
• ESM initialization pattern applied (separate

  instrument.mjs

  file)

• @sentry/tracing

  package removed (functionality built into core packages)
• Bundler plugins updated to v2.14.2+
• Post-migration test events captured successfully in Sentry dashboard
• Source maps verified, traces propagating across services

Error Handling

Cannot find module '@sentry/hub'

@sentry/node

Sentry.startTransaction is not a function

Sentry.startSpan()

new Integrations.X is not a constructor

Sentry.xIntegration()

Cannot find module '@sentry/tracing'

@sentry/node

@sentry/*

npm install @sentry/node@8 @sentry/browser@8

ERR_MODULE_NOT_FOUND

instrument.mjs

node --import ./instrument.mjs

@sentry/webpack-plugin

@sentry/vite-plugin

AttributeError: configure_scope

sentry_sdk.get_current_scope()

Transport.send must return object

{ statusCode: 200 }

makeRequest()

nvm install 20 && nvm use 20

See errors.md for additional error patterns.

Examples

Example 1: Full v7 to v8 JavaScript Migration

Request: "Upgrade our Express app from Sentry v7 to v8"

# Detect current state
npm ls 2>/dev/null | command grep "@sentry/"
# @sentry/node@7.114.0
# @sentry/tracing@7.114.0

# Run codemod
npx @sentry/migr8@latest

# Upgrade packages
npm install @sentry/node@8
npm uninstall @sentry/tracing

Before (v7 Express setup):

import * as Sentry from '@sentry/node';
import { Integrations } from '@sentry/tracing';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [new Integrations.Express({ app })],
  tracesSampleRate: 0.2,
});

app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.tracingHandler());
// ... routes
app.use(Sentry.Handlers.errorHandler());

After (v8 Express setup):

// instrument.mjs — must be separate file
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.2,
});

// app.mjs — run with: node --import ./instrument.mjs app.mjs
import express from 'express';
import * as Sentry from '@sentry/node';

const app = express();

// v8: Sentry auto-instruments Express — no manual handlers needed
// Sentry.Handlers.requestHandler() and tracingHandler() are removed
// Error handler replaced with Sentry.setupExpressErrorHandler()
Sentry.setupExpressErrorHandler(app);

app.listen(3000);

Result: SDK upgraded to v8.49.0,

@sentry/tracing

Example 2: Python v1 to v2 Migration

Request: "Upgrade sentry-sdk from 1.x to 2.x in our Flask app"

# Before (v1)
import sentry_sdk
from sentry_sdk.integrations.flask import FlaskIntegration

sentry_sdk.init(
    dsn="...",
    integrations=[FlaskIntegration()],
)

with sentry_sdk.configure_scope() as scope:
    scope.set_tag("deploy", "v2.1")

# After (v2)
import sentry_sdk
from sentry_sdk.integrations.flask import FlaskIntegration

sentry_sdk.init(
    dsn="...",
    integrations=[FlaskIntegration()],
)

scope = sentry_sdk.get_current_scope()
scope.set_tag("deploy", "v2.1")

Result: SDK upgraded to 2.x,

configure_scope

get_current_scope

push_scope

new_scope

Resources

• JavaScript v7 to v8 Migration Guide
• Node.js v7 to v8 Guide
• Express v7 to v8 Guide
• Python SDK v1 to v2 Migration
• @sentry/migr8 Codemod Tool
• Sentry SDK Changelog

Next Steps

• Run sentry-performance-tracing to configure v8 span-based tracing
• Run sentry-ci-integration to update CI source map upload after SDK change
• Run sentry-release-management to tag the upgraded release
• Run sentry-known-pitfalls to review common post-upgrade issues