Execute upgrade Sentry SDK and migrate between versions. Use when upgrading Sentry SDK, handling breaking changes, or migrating from legacy versions. Trigger with phrases like "upgrade sentry", "sentry migration", "update sentry sdk", "sentry breaking changes".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill sentry-upgrade-migrationLoading…
Detect installed Sentry SDK versions, identify breaking API changes, apply automated codemods, and verify the upgrade succeeds with test events and traces.
!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'
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.
@sentry/* packages at the same major version before starting# 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"
# 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
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 removed
// 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.
# 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)"
# 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
// 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.
Sentry.startTransaction is not a function or similar runtime errorssentry-trace header)@sentry/* packages alignedstartSpan(), integrations converted to functionsinstrument.mjs file)@sentry/tracing package removed (functionality built into core packages)| Error | Cause | Solution |
|---|---|---|
Cannot find module '@sentry/hub' | Package removed in v8 | Replace hub imports with @sentry/node scope APIs |
Sentry.startTransaction is not a function | API removed in v8 | Use Sentry.startSpan() callback pattern instead |
new Integrations.X is not a constructor | Classes removed in v8 | Use functional form: Sentry.xIntegration() |
Cannot find module '@sentry/tracing' | Package removed in v8 | Remove import; tracing is built into @sentry/node v8 |
| Mixed version runtime crash | Some @sentry/* at v7, others at v8 | Align all packages: npm install @sentry/node@8 @sentry/browser@8 |
ERR_MODULE_NOT_FOUND on startup | ESM init file missing or wrong path | Create instrument.mjs, run with node --import ./instrument.mjs |
| Source maps not resolving | Bundler plugin version incompatible | Update @sentry/webpack-plugin or @sentry/vite-plugin to v2.14.2+ |
Python AttributeError: configure_scope | API removed in Python SDK v2 | Use sentry_sdk.get_current_scope() instead |
Transport.send must return object | Custom transport missing return | Return { statusCode: 200 } from makeRequest() |
| Node.js version error | SDK v8 requires Node 18.19+ or 20.6+ | Upgrade Node.js: nvm install 20 && nvm use 20 |
See errors.md for additional error patterns.
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/[email protected]
# @sentry/[email protected]
# 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 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.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).