Troubleshooting

Common issues and how to resolve them.

Deployment Issues

Build Failures

Error: Module not found

Solution: Check package.json and ensure all dependencies are listed

Error: Build timeout

Solution: Optimize build process or increase timeout in settings

Error: Out of memory

Solution: Reduce bundle size or upgrade to higher tier

Deployment Stuck

1. Check build logs for errors
2. Verify all environment variables are set
3. Ensure no infinite loops in build scripts
4. Try canceling and redeploying

Runtime Errors

500 Internal Server Error

Common causes:

• Missing environment variables
• Database connection issues
• Unhandled promise rejections
• Memory limit exceeded

Debug steps:

1. Check application logs
2. Verify environment variables
3. Test database connection
4. Add error handling

404 Not Found

Common causes:

• Incorrect routing configuration
• Missing index.html for SPAs
• Case-sensitive file paths
• Wrong public directory

Solutions:

• Check route definitions
• Configure fallback routing
• Verify file names match imports
• Set correct build output

Performance Issues

Slow Load Times

Diagnosis:

1. Check network tab in DevTools
2. Run Lighthouse audit
3. Monitor Core Web Vitals
4. Check bundle size

Solutions:

• Enable compression
• Implement caching
• Optimize images
• Reduce JavaScript bundle

High Memory Usage

Symptoms:

• Random crashes
• Slow response times
• Out of memory errors

Solutions:

• Fix memory leaks
• Implement pagination
• Use streaming for large data
• Upgrade instance tier

Database Issues

Connection Errors

Error: Connection timeout

// Increase timeout
const db = new Database({
  connectionTimeout: 30000
});

Error: Too many connections

// Implement connection pooling
const pool = createPool({
  max: 20,
  idleTimeout: 30000
});

Query Performance

Slow queries:

1. Add indexes on frequently queried columns
2. Use query explain plans
3. Implement caching layer
4. Optimize query structure

Authentication Issues

Login Not Working

Check:

1. Cookie settings (SameSite, Secure)
2. CORS configuration
3. Session storage
4. HTTPS in production

Solutions:

// Correct cookie settings
res.cookie('session', token, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax'
});

Session Expired

Implement refresh tokens:

// Refresh token logic
if (isTokenExpired(accessToken)) {
  const newToken = await refreshToken(refreshToken);
  // Update session
}

Common Error Messages

“Cannot read property of undefined”

• Add null checks
• Use optional chaining
• Validate data structure

“CORS blocked”

• Configure CORS headers
• Check API URL
• Verify allowed origins

“Request entity too large”

• Increase body size limit
• Compress request data
• Chunk large uploads

Getting Help

Before Asking for Help

1. Check documentation
2. Search existing issues
3. Review error logs
4. Try basic debugging

When Reporting Issues

Include:

• Error message
• Steps to reproduce
• Environment details
• Relevant code snippets

Support Channels

• Documentation: docs.irresistible.dev
• Community: discord.gg/irresistible
• Email: support@irresistible.dev
• GitHub Issues: github.com/irresistible/issues