Known Issues and Their Fixes

This document lists known issues in the codebase that have been fixed multiple times and should not be broken again.

1. OTP Signup Race Condition (dodev app)

Status: ✅ FIXED (3 times - last fix: January 2025)
Documentation: apps/webs/dodev/docs/auth/OTP_RACE_CONDITION_FIX.md

Quick Summary

When users sign up with OTP verification, there's a race condition between Clerk's session establishment and the redirect to /welcome. This causes React Error #301 and "Application error" messages.

DO NOT:

• ❌ Add useAuth() or custom auth hooks to /sign-in or /sign-up pages
• ❌ Remove the reload logic from /welcome page
• ❌ Wrap the welcome page in complex auth logic
• ❌ Add deprecated redirect props to ClerkProvider

DO:

• ✅ Use Clerk hooks directly (useClerk, useUser) in welcome page
• ✅ Keep the post-OTP detection and reload logic in welcome page
• ✅ Show "Setting up your account..." during the transition
• ✅ Let Clerk components handle their own state in auth pages

If It Breaks Again

See the full documentation at apps/webs/dodev/docs/auth/OTP_RACE_CONDITION_FIX.md for the complete fix.

---

Adding New Known Issues

When documenting a new recurring issue:

1. Create a detailed fix document in the relevant app's docs folder
2. Add a summary here with a link to the full documentation
3. Update CLAUDE.md to reference the issue
4. Include clear DO and DON'T sections