ai-ops-templates/rules/common-fixes.md

Common Fixes

This document tracks recurring issues and their solutions. Update when new patterns are discovered.

---

React/Next.js Issues

Hydration Mismatch

Symptom: "Hydration failed because the server rendered HTML didn't match the client"

Solution:

// Use useEffect for client-only rendering
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return null

Event Handler Type Errors

Symptom: Type errors on onClick handlers

Solution:

// Always type the event parameter
onClick={(e: React.MouseEvent<HTMLButtonElement>) => handleClick(e)}
// For forms
onSubmit={(e: React.FormEvent<HTMLFormElement>) => handleSubmit(e)}

State Not Updating

Symptom: State updates not reflecting in UI

Solution:

// For arrays/objects, always create new references
setItems([...items, newItem])
setUser({ ...user, name: 'New Name' })

---

Tailwind CSS Issues

Dark Mode Not Working

Symptom: Dark mode classes not applying

Solution:

// tailwind.config.js
module.exports = {
  darkMode: 'class', // or 'media'
}

Custom Colors Not Applying

Symptom: Custom color classes not generating

Solution:

// tailwind.config.js - extend, don't replace
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'var(--primary)',
      }
    }
  }
}

---

Form Issues

Zod Validation Not Triggering

Symptom: Form submits with invalid data

Solution:

// Ensure resolver is passed correctly
const form = useForm<FormData>({
  resolver: zodResolver(formSchema),
  mode: 'onChange', // or 'onBlur', 'all'
})

React Hook Form Not Re-rendering

Symptom: Form values update but UI doesn't

Solution:

// Use watch or useWatch for reactive updates
const watchedValue = form.watch('fieldName')

---

Database/Supabase Issues

RLS Policy Blocking Queries

Symptom: "new row violates row-level security policy"

Solution:

-- Check policies on table
SELECT * FROM pg_policies WHERE tablename = 'your_table';

-- Add policy for authenticated users
CREATE POLICY "Users can insert own data"
ON your_table FOR INSERT
WITH CHECK (auth.uid() = user_id);

Connection Pool Exhausted

Symptom: "remaining connection slots are reserved"

Solution:

• Use Supabase connection pooling (port 6543)
• Close connections properly
• Use transaction mode for serverless

---

Deployment Issues

Build Fails on Server

Symptom: Works locally but fails in production

Common Causes:

1. Environment variables missing
2. Node version mismatch
3. Missing devDependencies in production

Solution:

# Check Node version
node --version

# Verify env vars are set
# Add to Coolify environment variables

Container Health Check Failing

Symptom: Container restarts repeatedly

Solution:

# docker-compose.yaml - increase health check interval
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

---

Type Errors

"Type X is not assignable to type Y"

Symptom: TypeScript errors in component props

Solution:

// Use proper type imports
import type { SomeType } from './types'

// For component props
interface ComponentProps {
  data: SomeType
  onClick?: () => void
}

---

Performance Issues

Slow Page Load

Diagnosis Steps:

1. Check Network tab for large payloads
2. Use Lighthouse for audit
3. Check for unnecessary re-renders

Quick Fixes:

// Memoize expensive computations
const memoizedValue = useMemo(() => computeExpensive(a, b), [a, b])

// Memoize components
const MemoizedComponent = memo(ExpensiveComponent)

// Code split
const HeavyComponent = lazy(() => import('./HeavyComponent'))

---

Update Log

Date	Issue	Solution Added
2026-03-06	Initial	Created document

To add new fixes: Update this file and increment version in _meta