Error Tracking

1. Get Sentry DSN

1. Create account at sentry.io
2. Create a new project (Next.js)
3. Copy your DSN (looks like https://xxx@xxx.ingest.sentry.io/xxx)

2. Configure Environment Variables

Add to .env:

# Sentry Error Tracking
SENTRY_ENVIRONMENT=development

# Server-side error tracking
SENTRY_DSN=https://1234567890abcdef1234567890abcdef@o123456.ingest.sentry.io/1234567

# Client-side error tracking
NEXT_PUBLIC_SENTRY_DSN=https://1234567890abcdef1234567890abcdef@o123456.ingest.sentry.io/1234567

Production:

SENTRY_ENVIRONMENT=production
SENTRY_DSN=https://your-real-dsn@o123456.ingest.sentry.io/1234567
NEXT_PUBLIC_SENTRY_DSN=https://your-real-dsn@o123456.ingest.sentry.io/1234567

3. Verify Setup

The app works fine without Sentry configured. If SENTRY_DSN is missing, error tracking is disabled but the app functions normally.

Stripe Webhook Failures

What it means: Payment processing failed

Where to look:

• Sentry → Issues → Search "stripe_webhook"
• Check subscription ID and customer ID in context
• Verify webhook secret is correct

Fix:

1. Check Stripe Dashboard → Webhooks → Logs
2. Verify STRIPE_WEBHOOK_SECRET matches
3. Ensure webhook URL is correct

Email Delivery Failures

What it means: Email failed to send (magic link, welcome, etc.)

Where to look:

• Sentry → Issues → Search "resend" or "email"
• Check Resend Dashboard for delivery status

Fix:

1. Verify RESEND_API_KEY is valid
2. Check sender domain is verified in Resend
3. Verify EMAIL_FROM is correct

Auth Errors

What it means: Google OAuth or magic link failed

Where to look:

• Sentry → Issues → Filter by "auth"
• Check error message for details

Fix:

1. Verify Google OAuth credentials
2. Check redirect URIs match exactly
3. Verify AUTH_SECRET is set

Database Errors

What it means: Database query failed

Where to look:

• Sentry → Issues → Search "prisma"
• Check database connection

Fix:

1. Verify DATABASE_URL is correct
2. Ensure database is running
3. Check if schema is up to date: pnpm db:push

API Routes

Use the error handler wrapper:

import { withErrorHandler } from "@/lib/error-handler";

export async function POST(request: NextRequest) {
  return withErrorHandler(
    async () => {
      // Your logic here
      return NextResponse.json({ success: true });
    },
    {
      context: "my-feature",
      tags: { feature: "custom" },
    }
  );
}

Expected Errors

For validation or expected errors, don't use Sentry:

import { createErrorResponse } from "@/lib/error-handler";

// This won't send to Sentry (expected error)
if (!isValid) {
  return createErrorResponse("Invalid input", 400);
}

Background Operations

For non-critical errors:

import { captureError } from "@/lib/error-handler";

try {
  await backgroundTask();
} catch (error) {
  // Log to Sentry but don't throw
  captureError(error, "background-task");
}

Logging

Use the logger for structured logging:

import { logger } from "@/lib/logger";

// Info (console only, not Sentry)
logger.info("User logged in", {
  context: "auth",
  userId: "123",
});

// Warning (console + Sentry)
logger.warn("Slow API response", {
  context: "api",
  metadata: { duration: 5000 },
});

// Error (console + Sentry)
logger.error(new Error("Failed"), {
  context: "payment",
  userId: "123",
});

✅ Do

• Log unexpected errors to Sentry
• Add context (user ID, feature name)
• Filter sensitive data
• Keep sample rates low in production

❌ Don't

• Log expected validation errors
• Log 404s or auth redirects
• Include sensitive data in error messages
• Over-log (increases quota usage)

Add Custom Tags

Sentry.setTag("feature", "custom-feature");
Sentry.setTag("plan", "pro");

Add User Context

Sentry.setUser({
  id: user.id,
  email: user.email, // Sentry hashes this
});

Add Breadcrumbs

Sentry.addBreadcrumb({
  category: "user-action",
  message: "User clicked button",
  level: "info",
});