openinvoice-docs
Troubleshooting

Common Issues

Solutions to common problems and issues

Authentication Issues

Can't Sign In

Symptoms: Unable to sign in, authentication errors

Solutions:

  1. Verify Clerk API keys are correct in .env.local
  2. Check Clerk Dashboard for application status
  3. Clear browser cache and cookies
  4. Try incognito/private browsing mode
  5. Verify redirect URLs match configuration

Organization Not Loading

Symptoms: Organization data not appearing

Solutions:

  1. Check organization exists in Clerk Dashboard
  2. Verify webhook is configured correctly
  3. Check database for organization record
  4. Verify user has organization membership
  5. Check browser console for errors

Database Issues

Migration Errors

Symptoms: Database migrations fail

Solutions:

  1. Check PostgreSQL is running
  2. Verify DATABASE_URL is correct
  3. Check database user has permissions
  4. Review migration files for errors
  5. Try resetting database: bun prisma migrate reset

Connection Errors

Symptoms: Can't connect to database

Solutions:

  1. Verify PostgreSQL is running
  2. Check connection string format
  3. Verify database exists
  4. Check firewall rules
  5. Test connection with psql

Payment Issues

Stripe Payments Not Working

Symptoms: Payments not processing, errors

Solutions:

  1. Verify Stripe account is connected
  2. Check Stripe API keys are correct
  3. Verify webhook is configured
  4. Check Stripe Dashboard for errors
  5. Review payment logs

Crypto Payments Not Detected

Symptoms: XRP payments not being detected

Solutions:

  1. Verify payment address is correct
  2. Check destination tag (for XRP)
  3. Verify payment amount matches
  4. Check WebSocket connection status
  5. Review crypto payment logs

Email Issues

Emails Not Sending

Symptoms: Invoice emails not being sent

Solutions:

  1. Verify Resend API key is correct
  2. Check from email is verified
  3. Review Resend Dashboard for errors
  4. Check email logs
  5. Verify webhook is configured

Email Delivery Issues

Symptoms: Emails sent but not delivered

Solutions:

  1. Check spam folder
  2. Verify domain is verified in Resend
  3. Check DNS records (SPF, DKIM)
  4. Review bounce reports
  5. Verify recipient email address

Invoice Issues

Invoice Not Generating

Symptoms: Recurring invoices not being created

Solutions:

  1. Verify cron job is running
  2. Check recurring invoice template is active
  3. Verify next generation date
  4. Check cron job logs
  5. Test manual invoice generation

Invoice PDF Not Generating

Symptoms: PDF download fails or is blank

Solutions:

  1. Check browser console for errors
  2. Verify invoice has line items
  3. Check PDF generation service
  4. Try different browser
  5. Review server logs

Performance Issues

Slow Loading

Symptoms: Pages load slowly

Solutions:

  1. Check database query performance
  2. Review network requests
  3. Check for N+1 queries
  4. Verify database indexes
  5. Review server resources

High Memory Usage

Symptoms: Application uses too much memory

Solutions:

  1. Check for memory leaks
  2. Review large data queries
  3. Optimize database queries
  4. Check image sizes
  5. Review server configuration

Integration Issues

Webhook Not Receiving Events

Symptoms: Webhooks not being received

Solutions:

  1. Verify webhook URL is accessible
  2. Check webhook secret matches
  3. Review webhook logs
  4. Test with ngrok (local development)
  5. Check firewall rules

API Errors

Symptoms: API requests failing

Solutions:

  1. Check API endpoint URLs
  2. Verify authentication tokens
  3. Review API rate limits
  4. Check request format
  5. Review error messages

General Troubleshooting Steps

1. Check Logs

  • Browser console (F12)
  • Server logs
  • Database logs
  • Integration logs (Stripe, Resend, etc.)

2. Verify Configuration

  • Environment variables
  • API keys
  • Database connection
  • Integration settings

3. Test Components

  • Test individual features
  • Isolate the problem
  • Check dependencies
  • Verify data

4. Clear Cache

  • Browser cache
  • Application cache
  • Database cache
  • CDN cache (if applicable)

5. Update Dependencies

bun update
# or
npm update

Getting Help

If you're still experiencing issues:

  1. Check Documentation - Review relevant guides
  2. Search Issues - Check GitHub issues
  3. Review Logs - Gather error logs
  4. Create Issue - Open a GitHub issue with details

Next Steps

Database Setup

Database configuration and migration guide

Payment Issues

Troubleshooting payment processing problems