Error Monitoring

Scout’s Error Monitoring feature allows you to track, triage, and resolve Node.js application errors directly within the Scout UI. By integrating with the existing APM agent, Scout provides enhanced context and filtering capabilities for comprehensive error management.

Installation

AIf you haven't already, set up Scout APM for Node.js.

BEnable error monitoring by setting the environment variable:

export SCOUT_ERRORS_ENABLED=true

Or pass it in your Scout configuration object:

// scout.js
const { init } = require("@scout_apm/scout-apm");

init({
  name: "My App",
  key: process.env.SCOUT_KEY,
  monitor: true,
  errorsEnabled: true,
});

CDeploy!

Once enabled, Scout will automatically begin capturing and organizing errors from your application.

Configuration Options

The following configuration settings are available for error monitoring. These can be set as environment variables with the SCOUT_ prefix or in your Scout configuration object.

Only errors_enabled is required to enable error monitoring. The rest are optional.

Express Integration

For Express applications, Scout provides two pieces of middleware that work together.

expressMiddleware() instruments your routes and populates request context. errorMiddleware() is a standard Express 4-argument error handler that automatically captures any errors passed to next(err) or thrown from route handlers.

// scout.js — require this first in your entry point
const { init } = require("@scout_apm/scout-apm");
init({ name: "My App", key: process.env.SCOUT_KEY, monitor: true, errorsEnabled: true });

// app.js
require("./scout"); // must be first

const { expressMiddleware, errorMiddleware } = require("@scout_apm/scout-apm");
const express = require("express");
const app = express();

// Scout request middleware — place before your routes
app.use(expressMiddleware({ requestTimeoutMs: 0 }));

// Your routes
app.get("/", (req, res) => res.send("Hello"));

// Scout error middleware — place after all routes
app.use(errorMiddleware());

app.listen(3000);

The error middleware automatically records the controller (route path), HTTP method, request URL, query parameters, body parameters, and session data alongside each captured error.

NestJS Integration

For NestJS applications, Scout provides nestErrorFilter() — a global exception filter that captures errors and returns an appropriate HTTP response.

// scout.ts — require this first in main.ts
const { init } = require("@scout_apm/scout-apm");
init({ name: "My App", key: process.env.SCOUT_KEY, monitor: true, errorsEnabled: true });

// main.ts
import "reflect-metadata"; // safe — no instrumented packages
require("./scout"); // must come before NestJS loads

const { NestFactory } = require("@nestjs/core");
const { AppModule } = require("./app.module");
const { nestMiddleware, nestErrorFilter } = require("@scout_apm/scout-apm");

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Scout request middleware — place before your routes
  app.use(nestMiddleware({ requestTimeoutMs: 0 }));

  // Scout error filter — registers as a global NestJS exception filter
  app.useGlobalFilters(nestErrorFilter());

  await app.listen(3000);
}

bootstrap();

nestErrorFilter() automatically records the route path, HTTP method, request URL, query/body parameters, and session data alongside each captured error. For HttpException subclasses the original status code is preserved; all other errors return 500.

Custom Error Reporting

In addition to automatically capturing unhandled exceptions, Scout provides captureError() for manually reporting errors with custom context.

Basic Usage

const { captureError } = require("@scout_apm/scout-apm");

try {
  JSON.parse(badInput);
} catch (e) {
  captureError(e);
}

With Custom Context

Pass a flat key-value object as the second argument. These values are shown alongside the error in the Scout UI.

captureError(e, { userId: req.user.id, plan: "pro" });

With Location Override

Use the third argument to specify where the error “lives” in your application — useful for background jobs or non-Express handlers.

captureError(e, { orderId: 42 }, {
  controller: "CheckoutController",
  action: "process",
});

Full Signature

captureError(
  error: Error | string | any,
  context?: Record<string, any>,
  opts?: {
    controller?: string | null;  // shown as location in APM
    action?: string | null;
    module?: string | null;
    name?: string;               // override the exception class name
    requestId?: string;
    requestUrl?: string;
    requestParams?: object;
    requestSession?: object;
  }
): void

Capturing String Errors

You can pass a string directly and Scout will wrap it in an Error object:

captureError("Something went wrong in the payment flow");

Automatic Capture

Scout automatically captures errors from three sources:

• Express error middleware — any error passed to next(err) or thrown synchronously from a route handler
• Unhandled promise rejections — via process.on("unhandledRejection", ...)
• Uncaught exceptions — via process.on("uncaughtException", ...). The error is captured and then re-thrown so Node.js default behavior is preserved.

Ignored Exceptions

You can suppress specific error classes from being reported using errorsIgnoredExceptions. Scout walks the full prototype chain, so subclasses are automatically suppressed as well.

// scout.js
const { init } = require("@scout_apm/scout-apm");

init({
  name: "My App",
  key: process.env.SCOUT_KEY,
  monitor: true,
  errorsIgnoredExceptions: ["RangeError", "MyCustomError"],
});

Or via environment variable (comma-separated):

export SCOUT_ERRORS_IGNORED_EXCEPTIONS=RangeError,MyCustomError

In this example, any error whose class or any ancestor class is named RangeError or MyCustomError will be silently dropped.

Error Context and Attributes

Scout automatically enriches each error with:

• Exception class — the error constructor name (or a custom name via opts.name)
• Stack trace — frames from your application code, with node_modules frames stripped
• Request data — URL, query/body parameters, and session (populated automatically by Express middleware)
• Location — controller and action where the error occurred
• Custom context — any key-value pairs you pass as the second argument to captureError()
• Host — the hostname of the server that reported the error

Data Retention

Scout retains individual errors for 30 days, and aggregate parent groups (total counts, first seen at (& sha), last error message, etc) indefinitely, providing sufficient time for analysis and resolution tracking. This retention period allows teams to:

• Identify recurring error patterns
• Analyze error trends over time
• Maintain historical context for resolved issues
• Support post-incident analysis and learning

Integration with APM

Error monitoring seamlessly integrates with Scout’s APM features:

• Performance Context: View error occurrences alongside performance traces
• Endpoint Analysis: Identify which endpoints generate the most errors
• Critical Endpoint Errors: Automatically prioritize errors from marked critical endpoints
• Time Correlation: Correlate errors with performance degradation events

For more detailed information on error management features, triage workflows, and team collaboration tools, see the main Error Monitoring documentation.

Not seeing errors?

Reach out to us at support@scoutapm.com for further support and troubleshooting assistance.