Troubleshooting

Here are some common issues you might encounter and how to fix them.

Mobile Issues

CocoaPods Issues

If you see errors related to CocoaPods, try cleaning the build folder and reinstalling pods.

cd ios
pod deintegrate
pod install

Metro Bundler Issues

If the bundler gets stuck, try clearing the cache.

npx expo start -c

Web Platform Issues

Hydration Mismatch Errors

If you see "Hydration failed because the initial UI does not match" errors:

  1. Theme-related: Ensure suppressHydrationWarning is on the <html> tag in layout.tsx
  2. Auth state: The AuthHydrator component handles this - don't access auth state in server components
  3. Date/time rendering: Use useEffect for time-sensitive content
// Bad - causes hydration mismatch
const date = new Date().toLocaleDateString();

// Good - renders client-side only
const [date, setDate] = useState<string>();
useEffect(() => {
setDate(new Date().toLocaleDateString());
}, []);

OAuth Callback Fails

Common OAuth Issues

OAuth problems are usually caused by redirect URI mismatches or CORS configuration.

  1. Check redirect URI: Must exactly match what's configured in OAuth provider
  2. Check CORS: Backend must allow your web origin
  3. Check cookies: Ensure you're not blocking third-party cookies in development
  4. Apple Sign In: Remember that Apple requires HTTPS - won't work on localhost

Debug with:

# Check backend logs
docker logs backend-container

# Verify CORS headers
curl -I http://localhost:8080/api/auth/session

Apple Sign In Not Working in Development

Apple Sign In requires HTTPS redirect URIs and will not work with http://localhost. Options:

  1. Use ngrok or Cloudflare Tunnel: Create an HTTPS tunnel to your backend
ngrok http 8080
# Use the https://xxx.ngrok.io/api/auth/callback/apple URL as your redirect URI
  1. Skip Apple in dev: Test Apple Sign In only in staging/production environments
  2. Use mobile: Apple Sign In works in development on the mobile app via native SDKs

Session Not Persisting

  1. Cookie settings: In development, cookies require SameSite=Lax and Secure=false
  2. Domain mismatch: Ensure frontend and backend are on the same domain (or properly configured for cross-domain)
  3. Check browser DevTools: Network tab -> Cookies to see if session cookie is being set

404 on Refresh (Deployed)

If routes work initially but 404 on refresh:

  1. Vercel: Should work out of the box
  2. Netlify: Install the @netlify/plugin-nextjs plugin
netlify.toml
[[plugins]]
package = "@netlify/plugin-nextjs"
Avoid SPA Redirects

Do NOT use SPA-style redirects on Netlify - Next.js uses SSR, not static file serving.

  1. Self-hosted Node.js: Ensure you're running next start (not serving static files)
  2. Docker/Nginx: Use a reverse proxy to the Node.js server, not static file serving

Build Fails with Module Errors

# Clear Next.js cache
rm -rf web/.next

# Reinstall dependencies
rm -rf web/node_modules
bun install
Still stuck?

Join our Discord server for help from the community.