Common Issues

Database Connectivity Issues

If the application fails to start or throws a "connection refused" error, check the following:

1. Database URL Configuration

Ensure your DATABASE_URL in the .env file follows the correct format:

DATABASE_URL=postgresql://<user>:<password>@localhost:5432/hcgai_db

• Neon Database: If using Neon, ensure you have appended ?sslmode=require to the string.
• Local Postgres: Ensure the password and username match your local PostgreSQL installation.

2. Service Status

Verify that the PostgreSQL service is actually running on your machine:

• macOS: brew services list
• Linux: sudo service postgresql status
• Windows: Check "Services" for "postgresql-x64".

3. Missing Tables (Drizzle Push)

If the database connects but the app fails when fetching data, the schema might not be synchronized. Run the migration tool:

npm run db:push

Note: Use --force only on new databases, as it may cause data loss on existing tables.

Port Conflicts (Address already in use)

By default, the server runs on port 5000. If you see an EADDRINUSE error, another process is using that port.

Identify and Kill the Process

macOS/Linux:

# Find the process ID (PID)
lsof -i :5000
# Kill the process
kill -9 <PID>

Windows (PowerShell):

# Find the PID
netstat -ano | findstr :5000
# Kill the process
taskkill /PID <PID> /F

Alternative: Change the Port

Modify the PORT variable in your .env file:

PORT=5050

SMTP & Email Failures

The application uses Nodemailer to send password reset emails. The default configuration is optimized for Hostinger.

1. Authentication Failures

If emails aren't sending, ensure SMTP_PASS in your .env is correct. If you are using Gmail or other providers, you may need an App Password rather than your standard account password.

2. Connection Timeouts

The app connects via Port 465 (SSL). Ensure your firewall allows outbound traffic on this port. If you are using a different provider (like SendGrid or Mailgun), you must update the SMTP host in simple-app-server.js:

// Lines 151-169 in simple-app-server.js
const config = {
  host: 'your-provider-host.com',
  port: 587, // Or 465
  secure: true,
  auth: {
    user: 'your-email@domain.com',
    pass: process.env.SMTP_PASS
  }
};

AI Chatbot Errors

The chatbot requires a valid OpenAI API Key to function.

"401 Unauthorized"

• Ensure OPENAI_API_KEY is present in .env.
• Verify the key has not expired and has sufficient credits on the OpenAI Dashboard.

"Module not found" or "fetch is not defined"

Ensure you are running Node.js v16 or higher. The application relies on modern fetch APIs and async patterns that are not supported in older Node versions.

Session & Authentication Issues

Persistent Logouts

The application uses connect-pg-simple to store sessions in the sessions table of your database. If users are logged out every time the server restarts:

1. Check if the sessions table exists in your database.
2. Ensure your SESSION_SECRET is defined in .env. If this changes on every restart, all existing session cookies become invalid.

Registration Errors

If registration fails with a 400 Bad Request, the email address likely already exists in the users table. You can check existing users via:

psql $DATABASE_URL -c "SELECT email FROM users;"