Back to integrations

Integrate Sentry with Strapi

‎An official Sentry plugin for Strapi. Sentry is an open-source error tracking with full stacktraces & asynchronous context.

tweet selection
Sentry and Strapi Integration.png

    These integration guides are not official documentation and the Strapi Support Team will not provide assistance with them.

    What Is Sentry?

    Sentry is a flight recorder for your application. It captures errors in real time and provides detailed insights into crashes. Sentry offers a comprehensive view of each issue, including full stack traces and essential context.

    For Strapi projects built with JavaScript and Node.js, Sentry provides the following features:

    • Automatic error capture: It automatically detects uncaught exceptions and API errors.
    • Detailed context: Includes OS info, browser details, and API endpoint data.
    • Performance metrics: Helps identify and resolve performance bottlenecks.
    • Breadcrumb trails: Shows the sequence of events leading to errors.
    • Code change links: Identifies the code changes that caused the errors.

    What sets Sentry apart is its immediate alerts when problems occur—no more waiting for frustrated user emails. Sentry’s powerful search and filtering tools help you focus on the most critical issues.

    For Strapi developers, integrating Sentry fills a crucial gap by shedding light on backend errors that might otherwise go unnoticed. In production environments where you can't simply check the console, Sentry provides essential visibility into issues.

    Adding Sentry to your Strapi application allows you to identify and fix issues quickly, improving both your development workflow and user experience.

    Why Integrate Sentry with Strapi

    Integrating Sentry with Strapi provides continuous monitoring for your application, capturing errors in real-time and delivering comprehensive context for each issue.

    With automatic error logging, you will be aware of problems before your users even report them. Every error in your Strapi backend is immediately captured and sent to Sentry, keeping you informed of your application's health.

    Each error is accompanied by rich context, including user information, environment details, and the specific actions that triggered the issue. Sentry also creates a timeline of events leading up to each error, known as breadcrumb trails, helping you trace what happened step by step. This makes it easier for developers to resolve complex bugs.

    When something breaks, Sentry shows you which code change caused it. The direct link between errors and commits reduces debugging time, allowing you to address problematic changes quickly.

    For Strapi applications in production, Sentry serves as a robust monitoring system, providing visibility into live environments without requiring the reproduction of issues locally.

    Keep in touch with the latest Strapi and Sentry updates

    triangle

    How to Integrate Sentry with Strapi

    Setting up Sentry with Strapi gives you comprehensive visibility into your application errors. This section walks you through the entire process, from setup to verification. The steps work for both self-hosted Strapi and can be adapted for Strapi Cloud.

    Prerequisites

    Before starting, make sure you have:

    • Strapi v4 or newer (the v3 plugin is no longer supported)
    • Compatible Node.js version
    • NPM or Yarn package manager
    • Active Sentry account with a project set up
    • Your Sentry project's DSN (Data Source Name)
    • Permissions to edit your Strapi config files
    • Network access from your server to Sentry

    Remember to use @strapi/plugin-sentry for Strapi v4 and above, as recommended in the official documentation.

    Installation

    To integrate Sentry with Strapi, you will need to install the official Sentry plugin for Strapi. Here's how to install the plugin:

    1. Add the plugin using your package manager:
    1yarn add @strapi/plugin-sentry
    1  or
    1npm install @strapi/plugin-sentry
    1. Get your Sentry DSN from your Sentry dashboard.
    2. Store your DSN in environment variables rather than hardcoding it in your files.

    The plugin needs configuration before it will start tracking errors.

    Configuration

    Set up the Sentry plugin by following these steps:

    1. Create or edit config/plugins.js with this Sentry config:
    1module.exports = ({ env }) => ({
2  sentry: {
3      dsn: env('SENTRY_DSN'),
4    },
5  },
6});
    1. These settings control:
      • enabled: Turns the plugin on or off
      • dsn: Connects to your Sentry project
      • sendMetadata: Includes extra debugging context
      • You can add more options for advanced use cases
    2. Add your DSN to your .env file:
    1SENTRY_DSN=https://<your_public_key>@sentry.io/<your_project_id>
    1. Restart your Strapi server to apply these changes.

    Always follow security best practices with credentials. Check the official docs for more details.

    Verification

    Check if your setup works correctly:

    1. Create a test error:
    1try {
2  // Force an error for testing
3  throw new Error('Test Sentry integration');
4} catch (error) {
5  strapi.plugin('sentry').service('sentry').sendError(error);
6}
    1. Check your Sentry dashboard for the error.
    2. Confirm these details in the dashboard:
      • The error appears in your project
      • Stack trace shows correctly
      • Metadata is included (if enabled)
      • Environment info is present

    Common issues include wrong DSN, network problems, or config mistakes in your plugins.js file.

    Customizing Your Sentry Integration with Strapi

    Fine-tuning your Sentry setup in Strapi transforms basic error-tracking into a powerful diagnostic system. With custom tagging and advanced options, you'll identify issues faster and resolve them before they affect users.

    Using Custom Tags

    Custom tags work like labels that make your errors searchable and sortable in Sentry. Here's how to add them:

    1strapi.plugin('sentry').service('sentry').sendError(error, (scope, sentryInstance) => {
2  scope.setTag('feature', 'content-manager');
3  scope.setTag('api_endpoint', '/api/articles');
4  scope.setTag('user_role', ctx.state.user?.role?.name || 'public');
5});

    These tags help you:

    • Group errors by specific content types
    • Find issues in particular API endpoints
    • See which user roles experience problems

    You can add even more context to make debugging easier:

    1scope.setUser({ id: user.id, username: user.username });
2scope.setExtra('request_payload', ctx.request.body);

    Advanced Configuration Options

    For deeper customization, you can access the raw Sentry instance:

    1const sentryInstance = strapi.plugin('sentry').service('sentry').getInstance();

    This gives you direct access to Sentry's lower-level features. You can also set advanced options in your config/plugins.js:

    1init: {
2  environment: env('NODE_ENV'),
3  release: env('RELEASE_VERSION', '1.0.0'),
4  tracesSampleRate: 1.0, // For performance monitoring
5  maxBreadcrumbs: 50,
6}

    These settings let you:

    • Mark errors with specific environments
    • Track issues across different releases
    • Monitor performance metrics
    • Control how much context gets captured with errors

    You can also build custom middleware to add error context at any point in your request flow, which is perfect for global error handling or complex reporting logic.

    If you're interested in further enhancing your Strapi application, consider exploring other must-have Strapi plugins that can improve functionality and streamline development.

    With these customizations, you will build an error-tracking system that provides you with deep insights into your Strapi application, helping you identify and resolve issues before users encounter them.

    Keep in touch with the latest Strapi and Sentry updates

    triangle

    An Example Project Integrating Sentry with Strapi

    Let's see how Sentry works with Strapi in a real-world scenario. Meet "ShopEase"—a fictional e-commerce platform using Strapi to manage products, users, and orders.

    Setting Up Sentry in ShopEase

    The ShopEase team added Sentry to their Strapi backend like this:

    1. Installed the official plugin:
    1npm install @strapi/plugin-sentry
    1. Set up the configuration in config/plugins.js:
    1module.exports = ({ env }) => ({
2  sentry: {
3    enabled: true,
4    config: {
5      dsn: env('SENTRY_DSN'),
6      sendMetadata: true,
7      init: {
8        environment: env('NODE_ENV'),
9        release: 'shopease@1.0.0',
10      },
11    },
12  },
13});
    1. Added the Sentry DSN to their .env file:
    1SENTRY_DSN=https://<your_public_key>@sentry.io/<your_project_id>

    Custom Error Handling and Tagging

    To make error tracking more useful, ShopEase built custom error handling:

    1. They created middleware to capture and tag API errors:
    1module.exports = (config, { strapi }) => {
2  return async (ctx, next) => {
3    try {
4      await next();
5    } catch (error) {
6      strapi.plugin('sentry').service('sentry').sendError(error, (scope) => {
7        scope.setTag('endpoint', ctx.request.url);
8        scope.setTag('method', ctx.request.method);
9        scope.setUser({ id: ctx.state.user?.id || 'guest' });
10      });
11      throw error;
12    }
13  };
14};
    1. For their order processing system, they added detailed tags:
    1try {
2  // Order processing logic
3} catch (error) {
4  strapi.plugin('sentry').service('sentry').sendError(error, (scope) => {
5    scope.setTag('feature', 'order_processing');
6    scope.setTag('order_id', order.id);
7    scope.setExtra('order_details', order);
8  });
9}

    Real Issues Identified and Resolved

    This setup helped ShopEase catch and fix several major problems:

    1. Payment Gateway Timeout: Sentry found errors tagged with feature:payment_processing showing timeouts during high traffic. They added retry logic and optimized their payment gateway code.
    2. Inventory Problems: Errors tagged with feature:inventory_update revealed race conditions causing overselling. They fixed it with proper database locking.
    3. Login Failures: Errors with endpoint:/api/auth/local tags exposed a bug in password resets, which they quickly patched.

    Strapi Open Office Hours

    If you have any questions about Strapi 5 or just would like to stop by and say hi, you can join us at Strapi's Discord Open Office Hours, Monday through Friday, from 12:30 pm to 1:30 pm CST: Strapi Discord Open Office Hours.

    For more details, visit the Strapi documentation and the Sentry documentation.

    FAQ

    Can Sentry help me identify which code change caused an error in Strapi?

    Yes, Sentry links errors to the code changes that caused them, helping you quickly identify and address problematic changes. This feature is particularly useful for Strapi developers looking to maintain high-quality code and reduce debugging time.

    Is Sentry compatible with all versions of Strapi?

    Sentry integration is recommended for Strapi version 4 or newer. The @strapi/plugin-sentry is specifically designed to work with these versions, as the plugin for v3 is no longer supported. Always verify compatibility and test error-tracking functionality after any Strapi updates.

    How can I customize Sentry integration in my Strapi project?

    Customizing Sentry in Strapi involves adding custom tags for error sorting, using the raw Sentry instance for advanced features, and configuring config/plugins.js for specific options like environment tagging, release tracking, and performance metrics. Custom tags and advanced options allow for deeper insights and more efficient debugging.

    What common challenges might I face when integrating Sentry with Strapi, and how can I address them?

    Common challenges include issues catching errors during the bootstrap function, version compatibility issues, and environment configuration challenges. These can be addressed by implementing custom error handlers, verifying plugin compatibility before Strapi upgrades, storing Sentry DSN in environment variables, and maintaining consistent settings across environments.

    How do I verify if Sentry is correctly set up with my Strapi application?

    To verify Sentry setup, create a test error in your Strapi application and check your Sentry dashboard for the error report. Ensure that the error appears with the correct stack trace, metadata, and environment info. Troubleshoot any issues like incorrect DSN or network problems if the error doesn't show up as expected.

    Where can I find more help or resources on Sentry integration with Strapi?

    For additional help or resources on integrating Sentry with Strapi, consider joining Strapi Open Office Hours, exploring the Sentry and Strapi documentation, or connecting with the community on Strapi and Sentry forums. These platforms offer valuable insights, troubleshooting tips, and best practices from experienced developers.

    tweet selection