Skip to main content

Installation Issues

Module Upload Failsโ€‹

Problem: The module zip file won't upload through the Perfex admin panel.

Causes & Solutions:

CauseSolution
File size exceeds PHP upload limitIncrease upload_max_filesize and post_max_size in php.ini to at least 64M
Server timeout during uploadIncrease max_execution_time in php.ini to 300
Permissions issueCheck that the modules/ directory is writable (chmod 755)

Alternative: Upload via FTP/SFTP instead:

  1. Extract the zip on your computer
  2. Upload the extracted folder to your-perfex/modules/
  3. Activate via Setup โ†’ Modules in the admin panel

Module Not Appearing After Uploadโ€‹

Problem: You uploaded the module but it doesn't appear in Setup โ†’ Modules.

Solutions:

  1. Make sure the folder structure is correct: modules/saas/ (not modules/saas-module/ or modules/saas/saas/)
  2. Check that all files were uploaded completely (compare file count)
  3. Clear your browser cache and refresh the page
  4. Check file permissions: the entire modules/saas/ directory should be readable by the web server

MySQL Verification Failsโ€‹

Problem: Clicking "Click here to verify server settings" shows an error.

Error: "Access denied for user"โ€‹

Cause: Wrong MySQL username or password.

Fix:

  1. Double-check your MySQL credentials
  2. If using cPanel, try using your cPanel username and password
  3. Test the credentials manually:
mysql -u your_username -p -h localhost
# Enter your password when prompted
# If you can log in, the credentials are correct

Error: "Can't connect to MySQL server"โ€‹

Cause: MySQL is not running or wrong host/port.

Fix:

  1. Check if MySQL is running: sudo systemctl status mysql
  2. Verify the host is correct (usually localhost)
  3. Verify the port is correct (usually 3306)
  4. If MySQL is on a different server, use that server's IP address

Error: "CREATE command denied"โ€‹

Cause: The MySQL user doesn't have permission to create databases.

Fix:

-- Log in to MySQL as root:
GRANT ALL PRIVILEGES ON *.* TO 'your_username'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Or in cPanel: Go to MySQL Databases โ†’ User Privileges โ†’ Check "ALL PRIVILEGES"

Blank White Page After Activationโ€‹

Problem: After activating the module, you see a blank white page.

Solutions:

  1. Check PHP error logs: Look at /var/log/apache2/error.log (Apache) or /var/log/nginx/error.log (Nginx)
  2. Enable error display temporarily: Add to your .htaccess or index.php: 
    ini_set('display_errors', 1);
    error_reporting(E_ALL);
  3. Check PHP version: Make sure you're running PHP 7.4 or higher
  4. Check memory limit: Set memory_limit = 256M in php.ini

Registration Form Not Showingโ€‹

Problem: The landing page doesn't show a registration form.

Solutions:

  1. Make sure you've created at least one plan in SaaS Management โ†’ Plans
  2. Check that registrations are enabled in SaaS Management โ†’ SuperAdmin Settings โ†’ Tenants Settings
  3. Verify the landing page URL is correct in Landing Page Settings
  4. Try selecting a different landing page template
  5. Clear your browser cache

Emails Not Being Sentโ€‹

Problem: Welcome emails, verification emails, or invoice emails are not sent.

Solutions:

  1. Configure SMTP in Perfex CRM: Go to Setup โ†’ Email โ†’ Email Settings
  2. Recommended SMTP services:
    • Gmail SMTP (free for up to 500 emails/day)
    • SendGrid (free tier: 100 emails/day)
    • Mailgun (free tier: 5,000 emails/month)
  3. Test email sending from Setup โ†’ Email โ†’ Send Test Email
  4. Check your spam folder โ€” emails might be landing there
info

SMTP is crucial! Without SMTP configured, no emails will be sent from your platform โ€” including verification emails, welcome emails, and invoices. Set this up first!

Tenant Database Not Createdโ€‹

Problem: Tenant signs up but their database isn't created.

Solutions:

  1. Verify MySQL credentials in SaaS Settings (click the verify button)
  2. Check if your MySQL user has CREATE DATABASE privilege
  3. If on shared hosting, check if you've reached your database limit
  4. Check the SaaS Activity Log for error details
  5. Check PHP error logs for MySQL-specific errors

"Maximum database connections" Errorโ€‹

Problem: Error about too many database connections.

Solutions:

  1. Increase MySQL max_connections in my.cnf: 
    [mysqld]
    max_connections = 200
  2. Restart MySQL: sudo systemctl restart mysql
  3. Consider optimizing your server (more RAM) if you have many tenants
tip

Issue resolved? If you're still having problems, check Domain & DNS Issues or contact Support.