JavaScript SDK reference

initBugStack before your routes, bugstackErrorHandler after them. The handler reports the error and passes it on, so your own error handling still runs. In Express 4, wrap async handlers with wrapExpressHandler so their errors reach it.

const { initBugStack, bugstackErrorHandler } = require('bugstack-sdk/express')

// After app creation:
app.use(initBugStack({
  apiKey: process.env.BUGSTACK_API_KEY,
  endpoint: process.env.BUGSTACK_ENDPOINT || 'https://dashboard.bugstack.ai/api/ingest/sdk',
}))

// ... your routes ...

// Before app.listen:
app.use(bugstackErrorHandler())

Initialize once in a module your route handlers import, and wrap each App Router route handler with withErrorCapture. It reports the error and re-throws it. Only the handlers you wrap are covered: server actions, server components and middleware are not.

// lib/bugstack.ts
import { ErrorCaptureClient, withErrorCapture } from 'bugstack-sdk'

ErrorCaptureClient.init({
  apiKey: process.env.BUGSTACK_API_KEY!,
  endpoint: process.env.BUGSTACK_ENDPOINT ?? 'https://dashboard.bugstack.ai/api/ingest/sdk',
})

export { withErrorCapture }

// app/**/route.ts: wrap each route handler
import { withErrorCapture } from '@/lib/bugstack'

export const GET = withErrorCapture(async (request) => {
  // ...your handler, unchanged
  return Response.json({ ok: true })
})

const { initBugStack, installGlobalHandlers, captureError } = require('bugstack-sdk/generic')

initBugStack({
  apiKey: process.env.BUGSTACK_API_KEY,
  endpoint: process.env.BUGSTACK_ENDPOINT || 'https://dashboard.bugstack.ai/api/ingest/sdk',
})

// Report uncaught exceptions and unhandled promise rejections.
installGlobalHandlers()

// Or report an error you handle yourself:
async function runJob(job) {
  try {
    await processJob(job)
  } catch (err) {
    await captureError(err, { job: job.id })
  }
}

An error passed to bugstackErrorHandler, an error thrown in a route handler wrapped with withErrorCapture or wrapExpressHandler, an uncaught exception or unhandled rejection once installGlobalHandlers() has run, and anything you pass to captureError. Nothing is hooked automatically by init alone, and browser errors are not captured.

Each report carries the error name, message and stack trace (with parsed frames), the route and method, query parameters and request headers with sensitive values redacted, the environment and the SDK version. Request bodies are off by default (captureRequestBody). A report is sent as soon as the error is captured, and retried up to five times with backoff if bugstack cannot be reached.

• captureError(error, metadata?) and its alias captureException, from bugstack-sdk/generic: report an error you handle. Resolves to true if it was sent rather than deduplicated.
• wrapFunction(fn, metadata?) and createErrorCapture(baseMetadata), from bugstack-sdk/generic: report errors from one function, or with the same metadata every time.
• wrapExpressHandler(handler), from bugstack-sdk/express: report errors from an async Express handler.
• withErrorCapture(handler), from bugstack-sdk: report errors from a Next.js App Router route handler.

Every option, with its type and default, is in the installation guide. The ones you are most likely to set: apiKey, endpoint, environment, enabled, captureRequestBody (default false), captureHeaders and captureQueryParams (default true), redactFields, shouldCapture and beforeSend.

Specialist agents work out the cause and write the change. It arrives as a pull request your own CI runs on. What happens next depends on the autonomy level you set for the repository: new repositories start on Review, where you merge. Before Autopilot merges a crash fix, bugstack replays the failing request: it must fail before the fix and pass after; without that proof the pull request waits for you. Connecting the repository also starts repository scanning.

Error patterns that come up often in production JavaScript applications. Each link opens a step-by-step fix guide:

• TypeError: Cannot read properties of undefined
• Hydration mismatch in Next.js
• Module not found: Can't resolve
• Unhandled promise rejection in Express
• CORS error on Express API routes
• Node.js JavaScript heap out of memory
• MaxListenersExceededWarning
• TypeError in React useState

No events in bugstack? Check that the API key is set when the process starts, and that endpoint is set to https://dashboard.bugstack.ai/api/ingest/sdk: the published SDK does not default to it yet. Turn on debug to see each send.

Events but no fix pull request? The bugstack GitHub App must be installed on the repository, and the files in the stack trace must be in that repository.

Too many duplicates? Each SDK sends the same error at most once every five minutes, and bugstack folds repeats within 24 hours into the same piece of work, so you get one pull request per problem.

Express errors not reported? bugstackErrorHandler() must come after your routes, and in Express 4 an error thrown in an async handler only reaches it through wrapExpressHandler or next(err).

The SDK sends the error, its stack trace, the route and method, query parameters and request headers. Authorization, cookie and API-key headers are always redacted, and sixteen sensitive field names (password, token, secret and the like) are redacted wherever they appear; add your own with redactFields, or change or drop a report with beforeSend. Request bodies are not sent unless you turn on captureRequestBody. See privacy and data handling.

bugstack-sdk follows semver. It needs Node.js 18 or later; Next.js 14 or later for the Next.js wrapper; Express 4 or 5. TypeScript types are included. The SDK has no native dependencies.

Sign up with GitHub and start Pro, or book a call and we set it up with you. Get started.

← Back to Documentation