Upgrade Sentry SDK versions and migrate breaking API changes.
Use when upgrading from Sentry v7 to v8, migrating Python SDK v1 to v2,
replacing deprecated Hub/Transaction APIs, or running the migr8 codemod.
Trigger: "upgrade sentry", "sentry migration", "sentry breaking changes",
"migrate sentry v7 to v8", "update sentry sdk".
Instrucciones de origen · Vista previa de solo lectura
name
sentry-upgrade-migration
description
Upgrade Sentry SDK versions and migrate breaking API changes.
Use when upgrading from Sentry v7 to v8, migrating Python SDK v1 to v2,
replacing deprecated Hub/Transaction APIs, or running the migr8 codemod.
Trigger: "upgrade sentry", "sentry migration", "sentry breaking changes",
"migrate sentry v7 to v8", "update sentry sdk".
Designed for Claude Code, also compatible with Codex and OpenClaw
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.
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(), converting class-based integrations to functions, and requiring ESM-first initialization. Python SDK v1 to v2 similarly replaces configure_scope() with get_current_scope(). This skill automates version detection, runs the official @sentry/migr8 codemod, applies manual fixes for patterns the codemod misses, and validates the upgrade with test events.
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 class-based integrations (replaced in v8)
command
"new Sentry\.\|new BrowserTracing\|new Integrations\."
"*.ts"
"*.js"
# Detect @sentry/tracing imports (package removed in v8)
command
"from '@sentry/tracing'"
"*.ts"
"*.js"
# Python: detect v1 scope API (replaced in v2)
command
"configure_scope\|push_scope"
"*.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)import { BrowserTracing } from'@sentry/tracing';
Sentry.init({
integrations: [newBrowserTracing()],
});
// v8 (NEW) — built into @sentry/browser and @sentry/nodeSentry.init({
integrations: [
Sentry.browserTracingIntegration(),
],
});
Breaking Change: ESM initialization requires separate file
// v7 (OLD) — init at top of entry fileimport * asSentryfrom'@sentry/node';
Sentry.init({ dsn: '...' });
// ... app code// v8 (NEW) — must be in separate file, loaded via --import// instrument.mjs (separate file)import * asSentryfrom'@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
// instrument.mjs — must be separate fileimport * asSentryfrom'@sentry/node';
Sentry.init({
dsn: process.env.SENTRY_DSN,
tracesSampleRate: 0.2,
});
// app.mjs — run with: node --import ./instrument.mjs app.mjsimport express from'express';
import * asSentryfrom'@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 removed, Express auto-instrumented, source maps verified, test error captured in dashboard.
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 replaced with get_current_scope, push_scope replaced with new_scope, Flask integration unchanged, test error captured.
