Skip to main content
This guide provides general advice for upgrading between Sentry SDK versions safely and efficiently.

​
Before You Upgrade

​
1. Review the Changelog

Always read the changelog for the target version:

​
2. Check Your Current Version

npm list @sentry/browser
# or
yarn list @sentry/browser

​
3. Review Deprecation Warnings

Upgrade to the latest version in your current major version first: 
# Example: If on 7.x, upgrade to latest 7.x
npm install @sentry/browser@^7.0.0
Fix all deprecation warnings before upgrading major versions.

​
Upgrade Strategies

​
Minor/Patch Upgrades

Minor and patch upgrades are safe and backwards compatible: 
# Update to latest patch
npm update @sentry/browser

# Update to specific version
npm install @sentry/[email protected]

​
Major Version Upgrades

Major upgrades require more care: 1. Test in Development First: 
# Install new version
npm install @sentry/browser@^10.0.0

# Run tests
npm test

# Test locally
npm run dev
2. Create a Branch: 
git checkout -b upgrade-sentry-v10
npm install @sentry/browser@^10.0.0
3. Update All Sentry Packages: 
# Update all @sentry/* packages to the same version
npm install \
  @sentry/browser@^10.0.0 \
  @sentry/react@^10.0.0
All Sentry packages should be on the same major version. Mixing versions can cause issues.
4. Run Migration Tool: For v7 to v8, use the automated migration tool: 
npx @sentry/migr8@latest
5. Manual Updates: Review and update code that the tool couldn’t fix automatically. 6. Test Thoroughly: 
npm run test
npm run build
npm run lint
7. Deploy to Staging: Test in a staging environment before production.

​
Upgrading Multiple Versions

If you’re several major versions behind: You can usually skip directly to the latest version: 
# From v7 directly to v10
npm install @sentry/browser@^10.0.0
Then review all migration guides:

​
Incremental Upgrades (Safer)

For large or complex applications: 
# Upgrade incrementally
npm install @sentry/browser@^8.0.0  # v7 → v8
# Test, fix issues
npm install @sentry/browser@^9.0.0  # v8 → v9
# Test, fix issues
npm install @sentry/browser@^10.0.0 # v9 → v10
# Test, fix issues

​
Common Upgrade Tasks

​
Update Import Statements

Major versions often reorganize exports: v7 to v8: 
// Before
import { BrowserTracing } from '@sentry/tracing';
import { Replay } from '@sentry/replay';

// After
import {
  browserTracingIntegration,
  replayIntegration,
} from '@sentry/browser';

​
Update Integration Syntax

v7 to v8: 
// Before
integrations: [new Sentry.Replay()]

// After
integrations: [Sentry.replayIntegration()]

​
Update Performance API

v7 to v8: 
// Before
const transaction = Sentry.startTransaction({ name: 'op' });
transaction.finish();

// After
import { startSpan } from '@sentry/browser';
startSpan({ name: 'op' }, () => {
  // Work here
});

​
Testing Your Upgrade

​
1. Unit Tests

Ensure existing tests pass: 
npm test

​
2. Type Checking

If using TypeScript: 
npx tsc --noEmit

​
3. Build

Ensure the project builds: 
npm run build

​
4. Manual Testing

Test key functionality:
  • Error capturing works
  • Performance monitoring works
  • Source maps work in production
  • Integrations work (Replay, Feedback, etc.)

​
5. Staging Deployment

Deploy to a staging environment and verify:
  • Events appear in Sentry
  • Stack traces are readable
  • Performance data is captured
  • No console errors

​
Rollback Plan

Always have a rollback strategy:

​
1. Git Revert

git revert <commit-hash>

​
2. Package Lock

Keep old package-lock.json or yarn.lock: 
git checkout main -- package-lock.json
npm install

​
3. Version Pin

Temporarily pin to old version: 
{
  "dependencies": {
    "@sentry/browser": "7.118.0"
  }
}

​
Framework-Specific Considerations

​
Next.js

Next.js SDK has additional requirements: 
// v8+ requires instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./sentry.server.config');
  }
}
See Next.js migration guide for details.

​
Node.js

v8+ requires initialization before imports: 
// MUST be first
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '__DSN__' });

// Then other imports
import express from 'express';

​
React

Update Error Boundary usage: 
// v9+ error types changed
<ErrorBoundary
  onError={(error: unknown) => {
    if (error instanceof Error) {
      console.log(error.message);
    }
  }}
>

​
Troubleshooting

Symptoms: TypeScript or build errorsSolutions:
  1. Update TypeScript: npm install typescript@latest
  2. Clear build cache: rm -rf node_modules/.cache
  3. Reinstall dependencies: rm -rf node_modules && npm install
Symptoms: Errors in production that don’t appear in developmentSolutions:
  1. Check source maps are uploaded correctly
  2. Verify release name matches between SDK and uploaded source maps
  3. Check browser compatibility (especially for v8+)
Symptoms: Events not appearing after upgradeSolutions:
  1. Check console for SDK errors
  2. Verify DSN is correct
  3. Check enabled option isn’t set to false
  4. Verify sampling rates aren’t too low
Symptoms: No transactions in SentrySolutions:
  1. Ensure tracesSampleRate is set: tracesSampleRate: 0.1
  2. Check integrations are loaded: browserTracingIntegration()
  3. For Node.js v8+, ensure Sentry is initialized first

​
Best Practices

​
1. Upgrade Regularly

Stay within 1-2 major versions of the latest:
  • Get new features and fixes
  • Easier upgrades (less breaking changes to handle)
  • Better security
  • Continued support

​
2. Use Version Ranges

Allow automatic patch updates: 
{
  "dependencies": {
    "@sentry/browser": "^10.0.0" // Gets 10.x.x updates
  }
}

​
3. Monitor Sentry Releases

Subscribe to releases:

​
4. Test Before Production

Always test in staging: 
# Staging deployment
NODE_ENV=staging npm run deploy

# Monitor for issues
# Then deploy to production
NODE_ENV=production npm run deploy

​
5. Keep Dependencies Updated

Update framework and build tools too: 
npm outdated
npm update

​
6. Document Your Configuration

Maintain documentation of your Sentry setup: 
// sentry.config.js
/**
 * Sentry Configuration
 * Version: 10.x
 * 
 * Features enabled:
 * - Performance monitoring (10% sampling)
 * - Session replay on errors
 * - User feedback
 * 
 * Last updated: 2024-03-05
 */
export const sentryConfig = {
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,
  // ...
};

​
Version-Specific Guides

v7 to v8

Major changes in v8

v8 to v10

Changes in v9 and v10

​
Getting Help

If you encounter issues during an upgrade:
  1. Check docs: docs.sentry.io
  2. Search issues: github.com/getsentry/sentry-javascript/issues
  3. Ask community: discord.gg/sentry
  4. Contact support: For paid plans

​
Upgrade Checklist

  • Review changelog and migration guides
  • Check current version
  • Create upgrade branch
  • Update all @sentry/* packages
  • Run migration tool (if available)
  • Update imports and API usage
  • Update configuration
  • Run tests
  • Test locally
  • Deploy to staging
  • Monitor staging for issues
  • Deploy to production
  • Monitor production
  • Update documentation

​
Next Steps

Setup Guide

Configure the SDK

Best Practices

Learn best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us