Skip to Content
TechnicalDevelopmentError Logging and Tracking

Error Logging and Tracking

This guide covers the automatic error logging and tracking system that captures all errors and creates Linear tickets for tracking and resolution.

System Overview

The error logging system automatically captures errors from multiple sources and creates Linear tickets for each unique error. The system works transparently without requiring manual intervention - all errors are automatically logged when they occur.

Error Types Covered

The following error types are automatically captured and logged to Linear:

Frontend Errors

  • React Component Errors: Errors that occur in React components are caught by the ErrorBoundary component
  • Unhandled JavaScript Errors: Errors that occur outside of React components are caught by the global window.onerror handler
  • Unhandled Promise Rejections: Async errors that aren’t caught by try/catch or .catch() are caught by the unhandledrejection event handler
  • API 5xx Server Errors: Server errors (500-599) from API requests are automatically logged
  • Network Failures: Connection errors and network failures are logged

Backend Errors

  • Uncaught Exceptions: Errors that occur in the Node.js process that aren’t caught
  • Unhandled Rejections: Promise rejections in the backend that aren’t handled

Error Types Not Covered

The following errors are not logged to Linear as they represent expected behavior:

  • 4xx Client Errors: Validation errors (400), authentication errors (401), authorization errors (403), not found errors (404), etc. These are expected client-side issues, not bugs
  • Aborted Requests: Network requests that are intentionally canceled
  • Expected Errors: Errors that are part of normal application flow

How It Works

Error Reporting Flow

  1. Error Occurs: An error happens in the application
  2. Error Handler Catches It: The appropriate error handler (ErrorBoundary, global handler, API interceptor, etc.) catches the error
  3. Error Reported to /error Endpoint: The error is sent to the backend /error endpoint with full context
  4. Linear Ticket Created: The backend creates a Linear ticket with all error details
  5. Ticket ID Returned: The ticket ID is returned and can be displayed to users (in production)

Linear Integration

  • Endpoint: POST /error
  • Authentication: Required (uses existing auth middleware)
  • Response: Returns ticket ID and success status
  • Duplicate Detection: Uses error digest to prevent duplicate tickets for the same error

Ticket Format

Each Linear ticket includes comprehensive information:

Quick Summary

  • Error type and message
  • Location where error occurred
  • Component/file information
  • Timestamp

Error Analysis

  • Root cause analysis
  • Severity assessment
  • Error category
  • Suggested fix

Context Information

  • Where It Happened: URL, path, route information
  • Environment: Browser, platform, screen resolution, memory usage
  • User Context: User ID, email, role (if authenticated)
  • Performance: Page load time, connection type
  • Technical Details: Full stack trace, component stack, error info

Backend Processing

  • Request ID for tracking
  • Processing time
  • Server information
  • Environment details

Duplicate Detection

The system uses error digests to detect duplicate errors:

  • Vite Error ID: If available, uses the error digest from Vite
  • Fallback ID: Generates a fallback ID based on error content
  • Existing Tickets: Checks for existing tickets with the same digest
  • Linking: If a duplicate is found, returns the existing ticket ID instead of creating a new one

Priority and Labels

  • Priority: All tickets are created with priority 4 (low) by default
  • Labels: Tickets are automatically labeled with the “bug” label
  • Manual Adjustment: Priority and labels can be adjusted in Linear after ticket creation

Viewing Tickets

  1. Access Linear: Open your Linear workspace
  2. Filter by Label: Filter tickets by the “bug” label
  3. Search: Search for specific error messages or ticket IDs
  4. Monitor: Set up notifications for new bug tickets

Manual Issue Reporting

If you need to manually report an issue that wasn’t automatically caught, you can email:

developers-47c2a754df68@intake.linear.app

This will create a Linear ticket directly. Include as much detail as possible:

  • Description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshots if relevant
  • Environment information

During Demos

The error logging system works automatically during demo preparation and live demos:

  • All Errors Logged: Any errors that occur during demos are automatically logged
  • No Manual Steps Required: The system works transparently in the background
  • Immediate Tracking: Errors are tracked immediately, so they can be addressed after the demo
  • No Interruption: Error logging doesn’t interrupt the demo flow

Configuration

Required Linear Configuration

The system requires the following environment variables:

  • LINEAR_API_KEY: Linear API key for authentication
  • LINEAR_TEAM_ID: Linear team ID for ticket creation

Error reporting to Linear lives in packages/services/src/linear.

Required Linear Labels

The following label must exist in your Linear workspace:

  • “bug”: Used to categorize all error tickets

Troubleshooting

If errors are not being logged, confirm you’re in production mode (errors are only sent to Linear in production), that LINEAR_API_KEY and LINEAR_TEAM_ID are set, and that the /error endpoint is reachable. Duplicate detection and context capture both depend on the error digest being generated correctly.

Last updated on
Database lifecycle — migrations, seeding & auditingDevelopment Workflow