# 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:**
```tsx
// 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:**
```tsx
// 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:**
```tsx
// 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:**
```js
// tailwind.config.js
module.exports = {
  darkMode: 'class', // or 'media'
}
```

### Custom Colors Not Applying
**Symptom:** Custom color classes not generating

**Solution:**
```js
// 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:**
```tsx
// 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:**
```tsx
// 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:**
```sql
-- 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:**
```bash
# Check Node version
node --version

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

### Container Health Check Failing
**Symptom:** Container restarts repeatedly

**Solution:**
```yaml
# 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:**
```tsx
// 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:**
```tsx
// 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