Error Handling & Sentry Monitoring

Relevant source files

The following files were used as context for generating this wiki page:

• src/configs/sentry/client.ts
• src/services/errors/convex.ts
• src/services/errors/types.ts
• src/services/errors/client.ts
• convex/lib/errors/index.ts
• convex/lib/sentry.ts
• next.config.ts

The Error Handling and Sentry Monitoring system provides a unified interface for detecting, classifying, and reporting runtime exceptions across the Next.js frontend and Convex backend. It utilizes Sentry for centralized logging and offers structured utilities to transform database-level errors into user-friendly notifications and actionable developer alerts.

Client-Side Sentry Configuration

The frontend initializes Sentry within the src/configs/sentry/client.ts file. It configures browser tracing, breadcrumbs, and third-party error filtering to ensure telemetry remains relevant to the project domain.

Initialization and Filtering

The system uses Sentry.init to set up the monitoring environment. A custom beforeSend hook attaches the document referrer to exceptions to aid in debugging navigation-related issues.

The thirdPartyErrorFilterIntegration specifically filters for frames containing gettreadtalks-app to reduce noise from browser extensions or external scripts.
Sources: src/configs/sentry/client.ts:16-43

Build-Time Integration

Sentry is integrated into the Next.js build process via withSentryConfig in next.config.ts. This configuration handles sourcemap uploads and release management. The Content Security Policy (CSP) header explicitly permits connections to Sentry ingestion endpoints.
Sources: next.config.ts:10, next.config.ts:58-82

Convex Error Classification

The system differentiates between expected client errors (4xx) and unexpected server failures (5xx) to prevent flooding Sentry with non-actionable data.

Logging Logic

The STATUS_TO_SHOULD_LOG map defines the reporting threshold based on HTTP status codes.

Status Code	Code Description	Should Log to Sentry
400	Bad Request	No
401	Unauthorized	No
403	Forbidden	No
404	Not Found	No
500	Internal Server Error	Yes
502	Bad Gateway	Yes
503	Service Unavailable	Yes

Sources: src/services/errors/convex.ts:13-26

Data Extraction

The getSentryConfig function derives Sentry metadata from ConvexError objects. It extracts errorCode, resource, resourceId, and field to build a diagnostic Fingerprint.
Sources: src/services/errors/convex.ts:88-132

Backend Error Utilities

The Convex backend uses a set of standardized "thrower" functions to maintain consistency in error responses. These functions wrap the native ConvexError with structured data.

Standardized Throwers

Function	HTTP Status	Purpose
throwAuthRequired()	401	User must be logged in.
throwForbidden()	403	User lacks permissions.
throwNotFound()	404	Resource does not exist.
throwDuplicateSlug()	409	Resource uniqueness violation.
throwValidationError()	422	Input data is invalid.

Sources: convex/lib/errors/index.ts:63-125

Structured Error Flow

When a mutation fails, it generates a structured error that is eventually caught by the frontend error service.

Manual Reporting API

The project provides a simplified wrapper for manual reporting via captureException and captureMessage. These functions handle Sentry scope management, including setting levels, tags, and custom fingerprints.

Scope Application

The applyScopeOptions helper ensures that metadata is correctly attached to the Sentry event before transmission. It supports:

• Level: fatal, error, warning, info, debug.
• Context: Structured data under the "Details" key.
• Fingerprint: Custom grouping keys for the Sentry UI.
  Sources: src/services/errors/client.ts:74-115

Manual Backend Ingest

For environments where the native Sentry integration is unavailable, convex/lib/sentry.ts provides a reportSentryException function. This function manually constructs a Sentry Envelope and POSTs it to the Sentry Ingest URL using fetch.

Error Types and Constants

The system uses TypeScript interfaces to enforce structure in error reporting.

Key Data Structures

• ErrorContext: Contains errorCode, field, resource, and statusCode.
• SentryConfig: Derived configuration including shouldLog, tags, and fingerprint.
• FingerprintKind: A union of specific domain strings such as auth, convex, mutation, or validation.
  Sources: src/services/errors/types.ts:16-92

The error handling framework ensures that developers receive high-fidelity alerts for system failures while maintaining a clean, non-intrusive experience for end-users encountering expected validation or permission errors.