Skip to main content

Troubleshooting

Solutions for common issues with self-hosted Synjar.

Application won't start​

Port already in use​

Error: EADDRINUSE: address already in use

Solution:

# Find what's using the port
lsof -i :6200

# Kill the process or change port
export PORT=6201

Database connection failed​

Error: Connection refused or timeout

Solution:

  1. Verify PostgreSQL is running: 
    docker-compose ps postgres
  2. Check connection string in .env
  3. Verify network connectivity: 
    docker-compose exec synjar nc -zv postgres 5432

Missing environment variables​

Error: Required environment variable not set

Solution:

  1. Check .env file exists
  2. Verify required variables are set
  3. Restart after changes: 
    docker-compose down && docker-compose up -d

Document processing issues​

Documents stuck in "Processing"​

Possible causes:

  1. OpenAI API issues
  2. Storage connection problems
  3. Worker crashed

Solutions:

  1. Check OpenAI API key: 
    curl https://api.openai.com/v1/models \
      -H "Authorization: Bearer $OPENAI_API_KEY"
  2. Verify storage connection
  3. Check logs for errors: 
    docker-compose logs synjar | grep -i error

Processing fails immediately​

Check:

  • File format supported (PDF, DOCX, TXT, MD)
  • File not corrupted
  • File not password protected
  • File contains text (not scanned images)

Search not returning results​

No results found​

  1. Document not ready: Wait for processing to complete
  2. Wrong workspace: Verify searching correct workspace
  3. Index issue: Re-upload document to re-index

Incorrect results​

  1. Be more specific: Add context to query
  2. Check document content: Verify expected text exists
  3. Embedding issue: Re-process document

Performance issues​

Slow response times​

Check:

  1. Database performance: 
    SELECT * FROM pg_stat_activity;
  2. Resource usage: 
    docker stats
  3. Network latency to services

High memory usage​

Solutions:

  1. Increase container memory limit
  2. Reduce concurrent connections
  3. Check for memory leaks in logs

Slow database queries​

# Enable slow query log
docker-compose exec postgres psql -U synjar -c \
  "ALTER SYSTEM SET log_min_duration_statement = 1000;"

Storage issues​

Upload fails​

Check:

  1. Storage credentials correct
  2. Bucket exists
  3. CORS configured (for web uploads)
  4. File size within limits

Files not accessible​

Check:

  1. Bucket permissions
  2. Endpoint URL correct
  3. Network connectivity

Email issues​

Emails not sending​

  1. Verify SMTP settings: 
    # Test SMTP connection
    nc -zv smtp.yourprovider.com 587
  2. Check credentials
  3. Verify FROM address is allowed

Emails going to spam​

  1. Configure SPF record
  2. Set up DKIM
  3. Use verified sending domain

Database issues​

Migration failed​

# Check migration status
docker-compose exec synjar npx prisma migrate status

# Reset if needed (DELETES DATA!)
docker-compose exec synjar npx prisma migrate reset

Disk space full​

# Check disk usage
docker system df

# Clean up
docker system prune -a

Getting help​

If these solutions don't help:

  1. Check GitHub Issues
  2. Search existing discussions
  3. Create new issue with:
    • Error message
    • Logs
    • Environment details
    • Steps to reproduce

See also​