Troubleshooting Runbooks

// Authentication problems?
→ See Authentication Issues

// Analytics not tracking?
→ See Analytics Issues

// AI chat not responding?
→ See AI & Chat Issues

// Database query errors?
→ See Database Issues

// Errors not appearing in Sentry?
→ See Observability Issues

// File uploads failing?
→ See Storage & Upload Issues

// Page loads slowly?
→ See Performance Issues

# Step 1: Check environment
echo $DATABASE_URL

# Step 2: Verify configuration
grep -r "config" app/

# Step 3: Test specific functionality
curl -X POST http://localhost:3000/api/test

// From runbook
import { useAuth } from "@repo/auth/client/next";
const { session, isLoading } = useAuth();

// Customize for your needs
if (isLoading) return <Spinner />;
if (!session) return <LoginPrompt />;

# Step 1: Check if AuthProvider is wrapping the app
grep -r "AuthProvider" app/providers.tsx
# Expected: <AuthProvider> wraps your app

# Step 2: Verify you're using correct imports
grep -r "useAuth" app/
# Must be: "use client"; import { useAuth } from "@repo/auth/client/next"
# NOT: import { useAuth } from "@repo/auth/server/next"

# Step 3: Check session retrieval
# In server components: const session = await auth.api.getSession()
# In client components: const { session } = useAuth()

// ✅ Correct: app/providers.tsx
"use client";
import { AuthProvider } from "@repo/auth/client/next";

export function Providers({ children }) {
  return <AuthProvider>{children}</AuthProvider>;
}

// ✅ Correct: app/dashboard/page.tsx (Client)
("use client");
import { useAuth } from "@repo/auth/client/next";

export function Dashboard() {
  const { session, isLoading } = useAuth();

  if (isLoading) return <div>Loading...;
  if (!session) return <div>Please log in;

  return <div>Welcome {session.user.name};
}

// ✅ Correct: app/api/user/route.ts (Server)
import { auth } from "@repo/auth/server/next";

export async function GET() {
  const session = await auth.api.getSession();
  if (!session) return new Response("Unauthorized", { status: 401 });
  return Response.json(session.user);
}

# Step 1: Check browser console for specific error
# Look for CORS, 401, 403, or auth-specific messages

# Step 2: Verify environment variables
echo $NEXT_PUBLIC_AUTH_URL
# Should be set to your app domain

# Step 3: Check password requirements
# Minimum 8 characters by default
# Check @repo/auth configuration

# Step 4: Test with curl
curl -X POST http://localhost:3000/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

// Ensure password meets requirements (8+ chars)
const password = "longpassword123"; // ✅ Good

// Check API endpoint is correct
const response = await fetch("/api/auth/signin", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password })
});

if (!response.ok) {
  // Log detailed error
  const error = await response.json();
  console.error("Auth error:", error);
}

# Step 1: Verify API key
echo $NEXT_PUBLIC_POSTHOG_KEY
# Should output your PostHog API key (starts with phc_)

# Step 2: Check network requests
# Open browser DevTools → Network tab
# Send an event and look for requests to:
#   - app.posthog.com
#   - your domain (if using proxy)
# Should see 200 OK responses

# Step 3: Verify AnalyticsProvider setup
grep -A 20 "AnalyticsProvider" app/providers.tsx

# Step 4: Check event naming
# Event names should not have special characters
# Only alphanumeric, underscores, spaces

// ✅ Step 1: Verify provider setup
// app/providers.tsx
"use client";
import { AnalyticsProvider } from "@repo/analytics/client/next";

export function Providers({ children }) {
  return (
    <AnalyticsProvider
      config={{
        providers: {
          posthog: {
            // Ensure API key is from environment
            apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY!,
            options: {
              api_host: "https://app.posthog.com",
              // Disable auto-capture if not needed
              capture_pageview: false,
              autocapture: false
            }
          }
        },
        debug: true // Enable debugging temporarily
      }}
    >
      {children}
    </AnalyticsProvider>
  );
}

// ✅ Step 2: Verify tracking code
("use client");
import { useAnalytics, track } from "@repo/analytics/client/next";

export function TrackingExample() {
  const analytics = useAnalytics();

  const handleClick = async () => {
    // Use valid event name (alphanumeric + underscores + spaces)
    const event = track("Button Clicked", {
      button_name: "submit", // underscores not spaces in property names
      timestamp: Date.now()
    });
    await analytics.emit(event);
  };

  return <button onClick={handleClick}>Click me</button>;
}

// ✅ Step 3: Check browser console for debug output
// With debug: true, should see:
// "[PostHog] Sending event: Button Clicked"

# Step 1: Verify feature flag exists in PostHog
# Go to PostHog dashboard → Feature Flags
# Check flag key matches your code

# Step 2: Check PostHog initialization
grep -r "posthog" app/
# Should see AnalyticsProvider or useAnalytics

# Step 3: Verify person/user identification
# Feature flags require user context
# Check that identify() is called before checking flags

// ✅ Correct flow: Identify THEN check flag
"use client";
import { useAnalytics } from "@repo/analytics/client/next";
import { useFeatureFlag } from "@repo/feature-flags/client";
import { useAuth } from "@repo/auth/client/next";
import { useEffect } from "react";

export function FeatureComponent() {
  const { session } = useAuth();
  const analytics = useAnalytics();
  const isEnabled = useFeatureFlag("beta-dashboard");

  useEffect(() => {
    // Step 1: Identify user FIRST
    if (session?.user) {
      analytics.identify(session.user.id, {
        email: session.user.email
      });
    }
  }, [session, analytics]);

  // Step 2: Then check flag
  if (!isEnabled) {
    return <OldDashboard />;
  }

  return <NewBetaDashboard />;
}

# Step 1: Check API keys
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY
# At least one provider key should be set

# Step 2: Check rate limits
# Look for 429 errors in logs
# Indicates rate limit exceeded

# Step 3: Verify model availability
# Some models may not be available in your region
# Check provider status pages

# Step 4: Check message length
# Very large messages may timeout
# Try with shorter test message

// ✅ Correct: Add timeout and better error handling
import { Chat } from "@repo/ai/generation";
import { logWarn, logError } from "@repo/shared";
import { getObservability } from "@repo/observability/server/next";

export async function POST(req: Request) {
  try {
    const { messages } = await req.json();

    // Set reasonable timeout
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s

    try {
      const stream = await Chat.stream(messages, {
        model: models.balanced,
        maxTokens: 500
      });

      clearTimeout(timeoutId);
      return stream.toUIMessageStreamResponse();
    } catch (error) {
      clearTimeout(timeoutId);
      throw error;
    }
  } catch (error) {
    // Log specific error
    const observability = await getObservability();

    if (error instanceof Error) {
      if (error.message.includes("429")) {
        logWarn("Rate limit exceeded", {
          endpoint: "/api/chat"
        });
        return new Response("Too many requests", { status: 429 });
      }

      if (error.message.includes("timeout")) {
        logError(error, {
          context: "chat-timeout"
        });
        observability.captureException(error, { context: "chat-timeout" });
        return new Response("Request timeout", { status: 504 });
      }
    }

    logError(error as Error, {
      context: "ai-chat"
    });
    observability.captureException(error as Error, { context: "ai-chat" });
    return new Response("AI service error", { status: 500 });
  }
}

# Step 1: Verify model name is correct
# Common formats:
# - OpenAI: gpt-4o, gpt-4-turbo, gpt-4o-mini
# - Anthropic: claude-3-5-sonnet-20241022
# - Google: gemini-2.0-flash-exp

# Step 2: Check provider API key
echo $ANTHROPIC_API_KEY
# If empty, Anthropic models won't work

# Step 3: Use model presets
# models.fast, models.balanced, models.reasoning
# These auto-select available models

// ✅ Use model presets (recommended)
import { models } from "@repo/ai";
import { generateText } from "ai";

const result = await generateText({
  model: models.balanced, // Auto-selects based on available keys
  prompt: "Hello"
});

// ✅ Or explicitly verify model availability
import { registry } from "@repo/ai/providers";

const availableModels = registry.getAvailableModels();
console.log("Available:", availableModels);
// Output: ["openai/gpt-4o", "anthropic/claude-3-5-sonnet", ...]

const modelName = "claude-3-5-sonnet-20241022"; // Full model name
const model = registry.languageModel(`anthropic/${modelName}`);

if (!model) {
  console.error(`Model not available: ${modelName}`);
  console.log("Available models:", availableModels);
}

# Step 1: Check Prisma is installed
grep "@repo/db-prisma" package.json
pnpm list @repo/db-prisma

# Step 2: Verify schema exists
ls -la packages/oneapp-shared/prisma/schema.prisma

# Step 3: Check client generation
pnpm exec prisma generate --schema=packages/oneapp-shared/prisma/schema.prisma

# Step 4: Verify DATABASE_URL
echo $DATABASE_URL
# Should output your database connection string

# ✅ Fix Prisma issues step-by-step
# 1. Reinstall Prisma
pnpm install @repo/db-prisma

# 2. Regenerate client
pnpm exec prisma generate --schema=packages/oneapp-shared/prisma/schema.prisma

# 3. Clear cache
rm -rf node_modules/.prisma

# 4. Reinstall
pnpm install

# 5. Verify DATABASE_URL is set
export DATABASE_URL="postgresql://user:password@localhost:5432/db"

// Step 1: Check what's unique in schema
// Look for @unique or @@unique in schema.prisma

// Step 2: Verify data before insert
const existingUser = await db.user.findUnique({
  where: { email }
});

if (existingUser) {
  console.error("User already exists with this email");
}

// Step 3: Check error details
try {
  await db.user.create({ data: { email } });
} catch (error) {
  if (error instanceof PrismaError && error.code === "P2002") {
    console.error("Unique constraint violated on:", error.meta?.target);
  }
}

// ✅ Handle unique constraints gracefully
import { db } from "@repo/db-prisma";

export async function createOrUpdateUser(email: string) {
  try {
    // Try to update first
    const user = await db.user.update({
      where: { email },
      data: { lastLogin: new Date() }
    });
    return user;
  } catch (error) {
    // If not found, create
    if (error?.code === "P2025") {
      return await db.user.create({
        data: { email, name: "New User" }
      });
    }
    throw error;
  }
}

// ✅ Or use upsert
const user = await db.user.upsert({
  where: { email },
  update: { lastLogin: new Date() },
  create: { email, name: "New User" }
});

# Step 1: Check Sentry DSN
echo $NEXT_PUBLIC_SENTRY_DSN
# Should be your Sentry project URL

# Step 2: Verify Sentry initialization
grep -r "Sentry.init" app/
# Should see initialization in sentry.client.config.ts and sentry.server.config.ts

# Step 3: Check error capture
# Enable Sentry debug mode temporarily
// sentry.server.config.ts
Sentry.init({
  debug: true, // Logs to console
  // ...
});

# Step 4: Verify environment
# Errors may not be sent in development
echo $NODE_ENV

// ✅ Proper error logging
import { logError } from "@repo/shared";
import { getObservability } from "@repo/observability/server/next";
import * as Sentry from "@sentry/nextjs";

export async function POST(req: Request) {
  try {
    // Business logic
    await riskyOperation();
  } catch (error) {
    // Method 1: Using shared logger + observability for error tracking
    logError(error as Error, {
      context: "api-endpoint"
    });
    const observability = await getObservability();
    observability.captureException(error as Error, {
      tags: { severity: "high" }
    });

    // Method 2: Direct Sentry capture (also works)
    Sentry.captureException(error);

    // Return safe error response
    return new Response("Internal error", { status: 500 });
  }
}

// ✅ Verify in development
// Set NODE_ENV=production locally to test error sending
// NODE_ENV=production npm run dev

# Step 1: Check storage credentials
echo $NEXT_PUBLIC_STORAGE_TYPE
# Should be "blob", "r2", or "images"

# Step 2: Verify bucket exists
# Depends on provider (Vercel Blob, R2, etc.)

# Step 3: Check file size limits
# Most providers have max file size limits
# Vercel Blob: 500MB max
# R2: 5TB max

# Step 4: Check network
# Large uploads may fail due to timeout
# Verify internet connection is stable

// ✅ Proper file upload with error handling
import { uploadFile } from "@repo/storage/client/next";
import { logError } from "@repo/shared";
import { getObservability } from "@repo/observability/client/next";

export async function handleFileUpload(file: File) {
  try {
    // Validate file
    const maxSize = 10 * 1024 * 1024; // 10MB
    if (file.size > maxSize) {
      throw new Error(`File too large. Max ${maxSize / 1024 / 1024}MB`);
    }

    // Upload with error handling
    const result = await uploadFile({
      file,
      bucket: "uploads"
    });

    if (!result) {
      throw new Error("Upload failed - no result returned");
    }

    return result;
  } catch (error) {
    // Log error for debugging
    logError(error as Error, {
      context: "file-upload",
      fileName: file.name,
      fileSize: file.size
    });
    const observability = await getObservability();
    observability.captureException(error as Error, {
      context: "file-upload",
      fileName: file.name,
      fileSize: file.size
    });

    // Show user-friendly message
    throw new Error("Upload failed. Please try again.");
  }
}

# Step 1: Check Web Vitals
# Use PageSpeed Insights: https://pagespeed.web.dev/

# Step 2: Enable performance monitoring
# Check observability configuration in your app
# Should send Web Vitals to Sentry/PostHog

# Step 3: Profile locally
# Use Chrome DevTools → Performance tab
# Record page load and identify slow tasks

# Step 4: Check bundle size
pnpm build
# Check .next/static/chunks/ sizes

// ✅ Optimize performance
// 1. Use dynamic imports for heavy components
import dynamic from "next/dynamic";
const HeavyComponent = dynamic(() => import("./HeavyComponent"), {
  loading: () => <div>Loading...,
});

// 2. Implement proper caching
export const revalidate = 3600; // Cache for 1 hour

// 3. Use React.memo for expensive renders
const MemoizedComponent = React.memo(MyComponent);

// 4. Monitor Web Vitals
import { useReportWebVitals } from "next/web-vitals";

export function WebVitalsReporter() {
  useReportWebVitals((metric) => {
    console.log(`${metric.name}: ${metric.value}ms`);
    // Send to analytics
  });
  return null;
}